From b79992553c8283bff09dad33b20ce194d00acfc0 Mon Sep 17 00:00:00 2001
From: Julien THOMAS <79689100+Mcthomas777@users.noreply.github.com>
Date: Mon, 1 Aug 2022 11:42:49 +0200
Subject: [PATCH] docs: Extend contribution parts with DoD hints (#94)

Co-authored-by: Julien THOMAS <external.julien.thomas@de.bosch.com>
---
 docs/conf.py                                |   1 +
 docs/getting_started/contribution_guide.rst | 125 ++++++++++++++++++++
 2 files changed, 126 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index 99043b80..852d388f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -49,6 +49,7 @@
     "sphinx.ext.viewcode",
     "sphinxcontrib.programoutput",
     "sphinx_autodoc_typehints",
+    "sphinx.ext.autosectionlabel",
 ]
 
 source_suffix = {
diff --git a/docs/getting_started/contribution_guide.rst b/docs/getting_started/contribution_guide.rst
index fdb89963..96bc8be3 100644
--- a/docs/getting_started/contribution_guide.rst
+++ b/docs/getting_started/contribution_guide.rst
@@ -59,4 +59,129 @@ Kiso-testing and make sure that you understand your rights and obligations.
 Any contributions to Kiso-testing project code base needs to be licensed under
 EPL v2.0.
 
+What should I do before committing ?
+------------------------------------
+
+PEP8-Compliancy
+---------------
+In order to maintain clear and user-friendly project, make sure that your
+changes respect PEP8 standards. PEP8 is a guide that provides Python coding
+conventions (naming, indentation,...).
+Official document : https://peps.python.org/pep-0008/
+
+To make sure your changes are PEP8 Compliant, different tools exist to help you
+here:
+    - linter (applicable on IDE) :
+        show some warning directly on IDE.
+    - pre-commit hook :
+        hook scripts that lint the added code using
+        flake8 and format it using black and isort.
+
+
+Typography
+----------
+Most of the comments made during PR-Reviewing are about typography/misspelling
+mistakes. An easy way to avoid these is by running
+`codespell <https://pypi.org/project/codespell/>`_ on your written code.
+
+
+Function type hinting
+---------------------
+In kiso-testing, every implemented function must have annotations for its
+parameters and return types (type hints). This results in increased readability and
+therefore in easier comprehension of the code for any reader.
+
+    .. code:: python
+
+        def some_fun(some_dict_param: dict, some_string_param: str) -> list:
+
+    .. note:: As not every types are available in the builtins, or as it is
+        important to precise inner type you might import some from collections
+        module or typing
+
+    .. code:: python
+
+        from typing import List
+        from collections import namedtuple
+
+        def some_fun(
+            some_int_list_param: List[int], some_imported_type_param: namedtuple
+        ) -> list:
+
+
+Unit Testing
+------------
+To ensure the correct behaviour of your code, add unit tests for every function
+you implemented.A convenient and pythonic way to do this is this is
+given by `pytest <https://docs.pytest.org/en/stable/>`_
+Code coverage is measured with `codecov <https://docs.codecov.com/docs>`_. It
+simply checks if the code coverage is not going lower than it was before changes.
+
+Examples Adaptation
+-------------------
+To ensure proper integration of your changes into the existing features,
+and demonstrate their usages, adapt the examples of modified module, and run
+it locally.
+
+Update Documentation
+--------------------
+Regarding documentation there are four main purposes that have to be fulfilled
+before committing :
+    - Documentation regarding the changes :
+        Make sure that the documentation allow easy understanding of the new
+        feature(s).This step mainly concern docstring (module, class, and function)
+        as shown below, but you could also have to change .rst documentation if
+        your changes concern general working principle of the ITF (e.g. cli)
+        To ensure proper formatting of the documentation, run ``invoke docs``
+        in the poetry environment.
+
+    .. code:: python
+
+        """
+        name_of_the_module
+        ******************
+
+        :module: name_of_the_module
+        :synopsis: short description of the module.
+
+        Extended description of the module's functionnality,
+        how it works, etc
+
+        .. currentmodule:: name_of_the_module
+        """
+
+    .. code:: python
+
+        class ClassName:
+        """Short description of class"""
+
+    .. code:: python
+
+        def fun(param1, param2):
+        """Short description of fun.
+
+        More extended description of the function
+        if needed.
+
+        :param param1: short description of param1
+        :param param2: short description of param2
+        :raise exception1: short description of raised exception
+
+        :return: short description of the return parameter
+        """
+
+    .. note:: Make also sure to do the type hinting for exceptions
+
+
+    - What's new section:
+        Add your changes into the what's new section, so user can stay updated of the
+        brand new features.
+
+    - Changelog:
+        Changelog is updated automatically with commit name. However commit names have
+        to respect specific norms. (Your changes concern a bug fix, commit name must be : "fix: commit name")
+        Further information on the naming can be found on: https://www.conventionalcommits.org/en/v1.0.0/)
+
+    - Documentation has to build properly.
+
 .. include:: getting_started_dev.rst