update contributing pages

    Following these best practices is recommended to contribute in

    [R2Devops/hub](https://gitlab.com/r2devops/hub/) repository

### 🧮 Variables

### 🤖 Job definition

#### 🧮 Variables

In order to be customizable, your job should use `variables`. This section

permits to define environment variables, usable by the job script.

    | `NEWMAN_FAIL_ON_ERROR` | Fail job on a request/test error | `true` |

    | `NEWMAN_ITERATIONS_NUMBER` | Number of Newman iterations to run (see [documentation](https://learning.postman.com/docs/running-collections/using-newman-cli/command-line-integration-with-newman/#misc)) | `2` |

### 🐳 Choose a Docker image

#### 🐳 Docker image

!!! info

    As described in [our guidelines](#guidelines), all jobs are run inside a

        * A large usage of the image can be a good indicator but take care, it

          doesn't guarantee the quality neither security of the image

### 📦 About artifact

#### 📦 Artifacts

The vast majority of jobs produce a result. This result can be of different

kinds:

* Check report

* Test report

* Build result

In both case, the result should be exposed by the job using

option. It permits to pass artifact to another job of the pipeline and

expose results to users.

!!! info

    In the case of a test report, you need to use `when: always` option under

    `artifacts` if you want to expose result even if job fails.

Artifact can be configured at different level of integration in Gitlab

interface:

2. Quick integration with [`artifacts:expose_as`](https://docs.gitlab.com/ee/ci/yaml/#artifactsexpose_as){:target=blank}

    !!! info

        In this case, you need to use `when: always` option under `artifacts`

        if you want to expose result even if job fails.

    This is a way to quickly integrate any format of report in Gitlab Merge

    Request interface. Technically, you don't have to format your report ouput

    in a specific format but we recommend to use `HTML` format. In this way,

3. Simple artifact without integration

    !!! info

        In this case, you need to use `when: always` option under `artifacts`

        if you want to expose result even if job fails.

    ??? example "Example of `artifacts`"

        Example: job [`trivy_image`](/jobs/dynamic_tests/trivy_image/) that

        use its output as `junit` report in `artifacts:repors:junit` section:

            when: always

        ```

#### 🔩 Keep genericity

### Compliance with another job

Jobs of the hub should remains as generic as possible, in order to ensure it:

* Compliance with another job

* Compliance with pages

* Try to avoid using `rules` options that is strongly linked to the context of

  user and so should be set by the user. Also, some feature requiring specific

  workflows, as [Gitlab Merge

  Trains](https://docs.gitlab.com/ee/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/){:target=blank}

  are more easily implemented by users if you don't specify `rules` in your

  job.

* Try to avoid using `before_script` and `after_script` to let users the

  possibility to redefine these options while exploiting to the maximum your

  job.

    Add this job to the list of documentation builder jobs in pages documentation

    The documentation output must be specified in a variable with the default value to documentation_build/ in order to be retrieved by pages job by default

!!! info

    Jobs of the hub can be dynamically

    [`customized`](/use-the-hub/#jobs-customization) by users. Customization

    works thanks to overriding of job options, so, in order to

### Documentation of your job `README.md`

### 📖 Job documentation

TODO

As described in [R2Devops/hub job

structure](/job-structure/#job-documentation), documentation of a job is

written inside its `README.md` file.

### How to test my job

!!! tip

    Don't hesitate to copy the documentation from another job as starting

    point. Example: raw content of [openapi

    `README.md`](https://gitlab.com/r2devops/hub/-/raw/latest/jobs/openapi/README.md)

TODO

We recommend to include following sections in your documentation:

* How can I test my job locally/easily ?

> Locally ? using the doxygen binary in my own operating system ? (brew install...)

> Using a blank repo in gitlab ?

> ex: https://gitlab.com/coconux/doxygen and link with the job in WIP Ex: - remote: 'https://gitlab.com/go2scale/hub/-/raw/111-add-doxygen-job/jobs/doxygen/doxygen.yml'

> How can I check the hub documentation went well ?

> Note about including a local job file

* Objective: describe the goal of your goal

* How to use it: a list of steps to quickly use your job

* Job details: describes details of job (name, docker image, stage, etc)

* Variables: table listing variables used by the job (name, description,

  mandatory)

* Artifacts: describes artifact defined by the job

### 🚄 Compliance with another job

### Advises to keep your job generic

Several jobs of the hub can be used together without any configuration. This is

currently implemented for all jobs producing an `HTML` output and the job

[`pages`](/jobs/deploy/pages/) which deploys the `HTML` on a webserver.

TODO

!!! info

    This feature is empowered by the `artifacts` option: jobs producing a

    static website output give it to the `pages` job trough an artifact stored

    in a standard path: `${CI_PROJECT_DIR}/website_build`.

* Try to avoid using `rules`: in majority of cases, `rules` of a job are

  specific to the project on which they will be used. If you use it, your job

  will loose its genericity. Also, some feature requiring specific workflows,

  as [Gitlab Merge

  Trains](https://docs.gitlab.com/ee/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/)

  are more easily implemented by users if you don't specify `rules` in your

  job.

So, if your job produce an static website output, ensure to store the result of

the build in `${CI_PROJECT_DIR}/website_build` and to configure this path as

artifact. See example in [`mkdocs`](/jobs/build/mkdocs/) job.

* Usage of `rules`, `before_script`, `after_Script`, ...

* Compliance with another job

* Compliance with pages

    Add this job to the list of documentation builder jobs in pages documentation

    The documentation output must be specified in a variable with the default value to documentation_build/ in order to be retrieved by pages job by default

### TODO in another issue

* Stage list in job file with only one stage: the one of the job

* Add contact us at each blocking issue points

* Describe our CI/CD pipeline

### 🧪 Test your job

In order to test your job before merging it into the hub, we recommend you to

follow these steps:

1. Test the behavior of your job inside a local container on your machine (with

   the same image than you want to use for the job). To simulate the Gitlab job

   that will run it on your project you can mount the repository folder inside

   the container:

      ```shell

      # Example if your job will uses node:15.7-buster as Docker image docker run -v

      /path/to/your/repo:/mnt --entrypoint "/bin/sh" -it node:15.7-buster

      ```

2. Create your job configuration in a repository and test it locally using

   [`include

   local`](https://docs.gitlab.com/ee/ci/yaml/#includelocal){:target=blank}

   instead of `remote` from the hub. Example:

    ```yaml

    include:

        - local: 'my-work-in-progress-job.yml'

    ```

!!! info

    * Jobs of the hub uses the Gitlab CI/CD configuration format

    * Jobs of the hub must specify a Docker image to be run in a container

    * See [GitLab CI/CD pipeline configuration reference](https://docs.gitlab.com/ee/ci/yaml/)

    * See [GitLab CI/CD pipeline configuration

      reference](https://docs.gitlab.com/ee/ci/yaml/){:target=blank}

    * See [R2Devops guidelines and best

      practices](/create-update-job/#guidelines) about

      job definition

Job definition usually contains the following fields:

* **[`variables`](https://docs.gitlab.com/ee/ci/yaml/#variables){:target="_blank"}**: variables used by the `script` part of the job to customize its behaviour

* **[`artifacts`](https://docs.gitlab.com/ee/ci/yaml/#artifacts){:target="_blank"}**: specify the result of the job that should be exposed to the user trough classic artifact or Gitlab reports

See our Best Practices and guidelines: TODO LINK

**Example of job definition [`gitleaks.yml`](https://r2devops.io/jobs/static_tests/gitleaks/):**

```yaml

| `maintainer` | Gitlab username of the maintainer | Yes |

| `license` | Open-source licence for the job. You can choose between `Apache-2.0` and `MIT` | Yes |

| `labels` | List of label describing the job | No |

| `images` | https://gitlab.com/r2devops/hub/-/merge_requests/129  | TODO |

| `tools` | https://gitlab.com/r2devops/hub/-/merge_requests/129  | TODO |

<!-- TODO after https://gitlab.com/r2devops/hub/-/merge_requests/129

| `images` | TODO | TODO |

| `tools` | TODO | TODO |

-->

**Example of `job.yml`:**