doc: add environments & Docker versions

Acceptance templates provide acceptance test tools (functional testing, performance testing, [DAST](https://en.wikipedia.org/wiki/Dynamic_application_security_testing)).

## Deployment environments

All our Deploy & Run templates support 4 kinds of environments (each being optional):

| Environment Type | Description                                       | Associated branch(es)                  |

| ---------------- | ------------------------------------------------- | -------------------------------------- |

| **Review**       | Those are dynamic and ephemeral environments to deploy your ongoing developments.<br/> It is a strict equivalent of GitLab's [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/) feature. | All **development branches** (non-integration, non-production) |

| **Integration**  | A single environment to continuously deploy your integration branch. | The **integration branch** (`develop` by default) |

| **Staging**      | A single environment to continuously deploy your production branch.<br/> It is an iso-prod environment, meant for running the automated acceptance tests prior to deploying to the production env. | The **production branch** (`master` or `main`  by default) |

| **Production**   | _Well.. the prod!_ | The **production branch** (`main` or `master`  by default) |

A few remarks:

* All our Acceptance templates support those environments and cooperate gracefully with whichever deployment technology you're using to test the right

  server depending on the branch it's running on.

* Transition from **Staging** to **Production** can be either automatic (if you feel confident enough with your automated acceptance tests) or _one-click_ (this is the default). This is configurable.

* If you're working in an organization where development and deployment are managed by separate teams, you may perfectly not declare any **Production** 

  environment in the development project, but instead trigger a pipeline in the project owned by the deployment team.

* [More info about deployment environments on Wikipedia](https://en.wikipedia.org/wiki/Deployment_environment).

## Generic pipeline stages

Our GitLab templates keep using a coherent set of generic GitLab CI [stages](https://docs.gitlab.com/ee/ci/yaml/#stages),

Now, here is a table that summarizes the generic templates behavior for each branch:

<table>

<table border="1">

<thead>

<tr>

<th>Stage/<br>Branch</th>

</tr>

</thead>

<tbody>

<tr style="background-color: #FF413640;">

<td><strong>production</strong> (<code>master</code>&nbsp;branch)</td>

<tr style="background-color: #0074D940;">

<td><strong>development</strong> (any branch other than <code>develop</code>, <code>main</code> or <code>master</code>)</td>

<td rowspan=3 style="vertical-align: middle; background-color: #ddd;">compile &amp; unit test</td>

<td rowspan=2 style="vertical-align: middle; background-color: #eee;"><strong>deep analysis</strong> / <strong>automatic</strong> trigger</td>

<td>create/deploy the <code>staging</code> environment</td>

<td rowspan=2 style="vertical-align: middle; background-color: #eee;"><strong>automatic</strong> trigger</td>

<td>create/deploy the <code>production</code> environment</td>

<td><strong>quick analysis</strong> <i>(when possible)</i>, or <strong>manual</strong> trigger</td>

<td>create/deploy a <code>review</code> environment</td>

<td><strong>manual</strong> trigger</td>

<td>N/A</td>

</tr>

<tr style="background-color: #FF851B40;">

<td><strong>integration</strong> (<code>develop</code>&nbsp;branch)</td>

<td rowspan=2 style="vertical-align: middle; background-color: #eee;"><strong>deep analysis</strong> / <strong>automatic</strong> trigger</td>

<td>create/deploy the <code>integration</code> environment</td>

<td rowspan=2 style="vertical-align: middle; background-color: #eee;"><strong>automatic</strong> trigger</td>

<td>N/A</td>

</tr>

<tr style="background-color: #0074D940;">

<td><strong>development</strong> (all other branches)</td>

<td><strong>quick analysis</strong> <i>(when possible)</i>, or <strong>manual</strong> trigger</td>

<td>create/deploy a <code>review</code> environment</td>

<td><strong>manual</strong> trigger</td>

<td>N/A</td>

<tr style="background-color: #FF413640;">

<td><strong>production</strong> (<code>main</code>&nbsp;or&nbsp;<code>master</code>&nbsp;branch)</td>

<td>create/deploy the <code>staging</code> environment</td>

<td>create/deploy the <code>production</code> environment</td>

</tr>

</tbody>

</table>

## Docker Images Versions

_to be continuous_ templates use - whenever possible - required tools as Docker images.

And when available, the _latest_ image version is used.

In some cases, using the latest version is a good thing, and in some other cases, the latest version is bad.

* _latest_ is **good** for:

    * DevSecOps tools (Code Quality, Security Analysis, Dependency Check, Linters ...) as using the latest version of the tool is the best way to ensure

      you're likely to detect vulnerabilities as soon as possible (well, as soon as new vulnerabilities are known and covered by DevSecOps tools).

    * Public cloud CLI clients as there is only one version of the public cloud, and the official Docker image is likely to evolve at the same time as the APIs.

* _latest_ is **not good** for:

    * Build tools as your project is developped using one specific version of the language / the build tool, and you would like to control when you change version.

    * Infrastructure-as-Code tools for the same reason as above.

    * Acceptance tests tools as the same reason as build tools.

    * Private cloud CLI clients as you may not have installed the latest version of - say - OpenShift or Kubernetes, and you'll need to use the client CLI version that matches your servers version.

!!! Success "To summarize"

    1. Make sure you explicitely override the Docker image versions of your build, Infrastructure-as-Code, private cloud CLI clients and acceptance tests tools matching your project requirements.

    2. Be aware that sometimes your pipeline may fail (without any change from you) due to a new version of DevSecOps tool that either highlights a new vulnerability (:tada:), or due to a bug or breaking change in the tool (:poop: happens).