update documentation

README.md

@@ -138,3 +138,48 @@ test-static-scan-gitleaks:
   variables:
     #SRC_PATH: "./"
 ```
+
+## Contributing
+The "Best practices" project is about
+* **A/** best practices documentation: as markdown documentation files in `X-best-practices` repositories. Each tech have their
+  own `X-best-practices` repository, on top of this generic one that applies to all
+* **B/** collection of shared piece of code: as part of the `X-nms-common` repository, or standalone. It is a gathering from
+  the smallest snippet to the fully standalone library, designed to be reused in projects. By design any shared piece of
+  code should follow and ease the implementation of what has been described in `X-best-practices`
+* **C/** collection of standardised Gitlab-CI jobs: as `yml` files in `/gitlab-ci` directory of the `X-best-practices` projects.
+  See [CI Best practices](https://code.europa.eu/digit-c4/dev/ci-best-practices)
+
+The lifecycle of **A/** and **B/** is as follows:
+1. The input comes from
+   * Document from compliance = high level contract requirement
+   * Lesson learned from a R&D project, PoC, experience, etc.
+2. Structure into x-Best practice.
+3. Eventually distribute a solution implementation in the X-nms-common project
+   1. Example snippet
+   2. Boilerplate
+   3. Template
+   4. Library, distributed via git.
+      ```shell
+      pip install git@code.europa.eu:digit-c4/dev/perl-nms-common.git
+      ```
+   5. Library, distributed with Gitlab package registry
+      ```toml
+      # pyproject.toml
+      [[tool.poetry.source]]
+      name = "code.europa.eu"
+      url = "https://code.europa.eu/api/v4/projects/digit-c4%2Fdev%2Fnetbox-nms-common/packages/pypi/simple"
+      priority = "explicit"
+   
+      [tool.poetry.dependencies]
+      netbox-nms-common = {version = "==0.3.0", source = "code.europa.eu"}
+      ```
+4. The `x-nms-common` is an "incubator" for shared code content. If a module becomes too important,
+   it should be extracted from x-nms-common as standalone library with its own lifecycle.
+
+The lifecycle of **C/** is as follow
+1. Find project with existing .gitlab-ci, but hardcoded `script` job section
+2. identify the related `x-best-practices` project, create the equivalent job template
+3. Optionally create a dedicated Docker image for the job template
+4. Create a merge request in the initially identified project to use the newly created job template
+
+NB: Step 1 could also be to identify projects without `.gitlab-ci.yml`, and suggest existing/new pipelines to implement