From 2ae363b6fef7ddf9e9f1f0e29a6be8f993cbf7d2 Mon Sep 17 00:00:00 2001
From: Daniel Dehennin <daniel.dehennin@ac-dijon.fr>
Date: Fri, 11 Mar 2022 13:24:39 +0100
Subject: [PATCH] docs(getting-started): we factorize the job templates per
 topic

Instead of having files with executable jobs, we define only hidden
template jobs that users must `instanciate` in their own
`.gitlab-ci.yml`.
---
 docs/GETTING-STARTED.md | 320 ++++++++++++++++++++--------------------
 1 file changed, 162 insertions(+), 158 deletions(-)

diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md
index 68a45da..605627c 100644
--- a/docs/GETTING-STARTED.md
+++ b/docs/GETTING-STARTED.md
@@ -14,26 +14,26 @@ contribution to make sure everything can be integrated correctly.
 
 In Gitlab, the [CI](https://docs.gitlab.com/ee/ci/) configuration is
 done in a file called
-[.gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/gitlab_ci_yaml.html)
+[`.gitlab-ci.yml`](https://docs.gitlab.com/ee/ci/yaml/gitlab_ci_yaml.html)
 in the root directory of the sources of a project.
 
 Every branches with that file could run some pipeline if configured.
 
 We will see 5 main `.gitlab-ci.yml` concepts in this documentation:
 
-- the [rules](#rules) permit to include or exclude jobs in a pipeline,
-  an empty pipeline does not run.
-- the [stages](#stages) to group jobs together and define the order of
-  execution of the groups
-- [include](#include) to reuse configuration files across projects
-- the [extends](#extends) to reuse configuration sections
-- the [jobs](#jobs) them-self to execute action in the pipeline.
+- the [`rules`](#rules) permit to include or exclude jobs in a
+  pipeline, an empty pipeline does not run.
+- the [`stages`](#stages) to group jobs together and define the order
+  of execution of the groups
+- [`include`](#include) to reuse configuration files across projects
+- the [`extends`](#extends) to reuse configuration sections
+- the [`jobs`](#jobs) them-self to execute action in the pipeline.
 
 ### Rules
 
 Instead of defining again and again the
-[rules](https://docs.gitlab.com/ee/ci/yaml/#rules) to apply to jobs,
-we define a [common set of rules](templates/Rules.yaml) to be used
+[`rules`](https://docs.gitlab.com/ee/ci/yaml/#rules) to apply to jobs,
+we define a [common set of `rules`](templates/Rules.yaml) to be used
 directly by jobs.
 
 For example, to make a job run only on the `dev` branch:
@@ -41,7 +41,7 @@ For example, to make a job run only on the `dev` branch:
 ```yaml
 include:
   # We include the definitions before using them
-  - project: EOLE/infra/ci-tools
+  - project: EOLE/Infra/ci-tools
     ref: stable
     file: /templates/Rules.yaml
 
@@ -51,23 +51,24 @@ run-only-on-dev:
     - echo "I'm running only on $DEV_BRANCH"
 ```
 
-The [rules template](templates/Rules.yaml) define variables for the
+The [`rules` template](templates/Rules.yaml) define variables for the
 default branch names:
 
 - `STABLE_BRANCH`: default to `stable`
-- `DEV_BRANCH`: default to `dev`
 - `TESTING_BRANCH`: default to `testing`
+- `ALPHA_BRANCH`: default to `alpha`
+- `DEV_BRANCH`: default to `dev`
 
 ### Stages
 
-The [stages](https://docs.gitlab.com/ee/ci/yaml/#stages) can be
+The [`stages`](https://docs.gitlab.com/ee/ci/yaml/#stages) can be
 whatever you want, the `ci-tools` templates use 3 stages by default:
 
-- `lint` for [`commitlint`](#validate-commit-messages)
-- `build` for [`.build-docker-image`](#building-images)
+- `lint` for [`.git:commitlint`](#validate-commit-messages)
+- `build` for [`.docker:image:build`](#building-images)
 - `release` for
-  [`semantic-release`](#generate-release-with-semantic-version-scheme)
-  and [`.tag-docker-image`](#tagging-docker-images)
+  [`.semantic-release:stable`](#generate-release-with-semantic-version-scheme)
+  and [`.docker:image:tag`](#tagging-docker-images)
 
 The order of `stages` list is important, `lint` should come first,
 then `build` and finally `release` to publish the build results.
@@ -82,22 +83,24 @@ provides templates to be
 ```yaml
 include:
   # We include the definitions before using them
-  - project: EOLE/infra/ci-tools
+  - project: EOLE/Infra/ci-tools
     ref: stable
     file: /templates/Rules.yaml
-  - project: EOLE/infra/ci-tools
+  - project: EOLE/Infra/ci-tools
     ref: stable
-    file: /templates/Lint/Commitlint.yaml
+    file: /templates/Git.yaml
 
 stages:
   - lint
+
+commitlint: {extends: '.git:commitlint'}
 ```
 
 ### Extends
 
 The [extends](https://docs.gitlab.com/ee/ci/yaml/#extends) keyword
 permits to merge different YAML jobs together, the most common case
-use [hidden template
+uses [hidden template
 jobs](https://docs.gitlab.com/ee/ci/yaml/yaml_optimization.html) (with
 names starting by a dot `.`).
 
@@ -105,7 +108,7 @@ names starting by a dot `.`).
 .alpine-common:
   image: "$ALPINE_IMAGE"
   variables:
-    ALPINE_IMAGE: "hub.eole.education/proxyhub/library/alpine:latest"
+    ALPINE_IMAGE: "alpine:latest"
     FOO: "this is FOO in .alpine-common"
   before_script:
     - echo "I run before any other 'script'"
@@ -131,11 +134,15 @@ Before using the CI tools templates, you must setup your repository.
 You must create the branches[^1] required to your release cycle:
 
 1. create the `dev` branch and [set it as default](https://docs.gitlab.com/ee/user/project/repository/branches/default.html)
-2. create the `testing` branch if you want a staging area where to
+2. create the `alpha` branch if you want a staging area where to
    stabilise your project before release
-3. create the `stable` branch where the releases are kept if you don't want to keep the default name (`master` or `main` depending of the configuration of your Gitlab)
+3. create the `stable` branch where the releases are kept if you don't
+   want to keep the default name (`main`, `stable` or `master` depending of the configuration of your Gitlab)
 
-[^1]: The branch names can be configured by setting the `DEV_BRANCH`, `TESTING_BRANCH` and `STABLE_BRANCH` variables in your own [.gitlab-ci.yml](https://docs.gitlab.com/ee/ci/variables/#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file)
+[^1]: The branch names can be configured by setting the `DEV_BRANCH`,
+    `ALPHA_BRANCH`, `TESTING_BRANCH` and `STABLE_BRANCH` variables in
+    your own
+    [.gitlab-ci.yml](https://docs.gitlab.com/ee/ci/variables/#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file)
 
 ### Protect your release cycle branches and tags
 
@@ -152,9 +159,9 @@ or `Developpers + Maintainers`.
 
 Finally, you must [protect the release tag
 pattern](https://docs.gitlab.com/ee/user/project/protected_tags.html)
-`release/*` with only push allowed for `Maintainers` used by
+`release/` with only push allowed for `Maintainers` used by
 `semantic-release`. That's the reason why the [release tag
-rules](templates/Rules.yaml#L154) run only on protected tags.
+rules](templates/Rules.yaml#L168-170) run only on protected tags.
 
 ### Create the `GITLAB_TOKEN` access token
 
@@ -215,16 +222,16 @@ you need mostly 4 steps:
    # vim: ft=yaml
    ---
    include:
-     - project: EOLE/infra/ci-tools
+     - project: EOLE/Infra/ci-tools
        ref: stable
        file: /templates/Rules.yaml
-     - project: EOLE/infra/ci-tools
+     - project: EOLE/Infra/ci-tools
        ref: stable
-       file: /templates/Lint/Commitlint.yaml
-     - project: EOLE/infra/ci-tools
+       file: /templates/Git.yaml
+     - project: EOLE/Infra/ci-tools
        ref: stable
-       file: /templates/Release/Semantic-release.yaml
-     - project: EOLE/infra/ci-tools
+       file: /templates/Semantic-release.yaml
+     - project: EOLE/Infra/ci-tools
        ref: stable
        file: /templates/Docker.yaml
 
@@ -251,7 +258,7 @@ you need mostly 4 steps:
      variables:
        TARGET_BRANCH: $DEV_BRANCH
      # We use whatever image that has git
-     image: 'hub.eole.education/eole/commitlint:latest'
+     image: 'bitnami/git:latest'
      script:
        - echo -e "\e[0Ksection_start:`date +%s`:has_branch[collapsed=true]\r\e[0KCheck that '${TARGET_BRANCH}' branch exists upstream"
        - 'git fetch --all'
@@ -275,7 +282,7 @@ you need mostly 4 steps:
    ###############################################################################
    # `lint` stage: `commitlint`
    ###############################################################################
-   # the `commitlint` is defined in `templates/Lint/Commitlint.yaml` included before
+   commitlint: {extends: '.git:commitlint'}
 
 
    ###############################################################################
@@ -287,8 +294,7 @@ you need mostly 4 steps:
    # - for `$DEV_BRANCH`
    # - on release tags (stable and testing) after the application
    #   versions are updated by `semantic-release`
-   build-docker:
-     extends: .build-docker-image
+   .build-docker-rules:
      rules:
        # The ordering is CRITICAL
        - !reference [.rules-map, not-on-schedule]
@@ -298,7 +304,12 @@ you need mostly 4 steps:
        - !reference [.rules-map, not-on-stable]
        - !reference [.rules-map, not-on-testing]
        - !reference [.rules-map, not-on-semantic-release-commit]
-       - !reference [.rules-map, on-branch]
+       - !reference [.rules-map, on-branches]
+
+   build-docker:
+     extends:
+       - .docker:image:build
+       - .build-docker-rules
 
 
    ###############################################################################
@@ -306,8 +317,8 @@ you need mostly 4 steps:
    ###############################################################################
    useless-test:
      stage: test
-     extends: .not-on-stable
-     # Use the previously built image
+     # Use the previously built image, so reuse the same `rules`
+     extends: .build-docker-rules
      image: "${CI_REGISTRY_IMAGE}/${IMAGE_NAME}:git-${CI_COMMIT_SHORT_SHA}"
      script:
        - echo "I successfully ran in ${IMAGE_NAME}:git-${CI_COMMIT_SHORT_SHA}"
@@ -317,35 +328,20 @@ you need mostly 4 steps:
    # `release` stage: `semantic-release`, `testing-prerelease`,
    #                  `merge-to-dev`, `tag *`
    ###############################################################################
-   # the `semantic-release` is defined in `templates/Release/Semantic-Release.yaml`
+   # Create the release versions on `$STABLEE_BRANCH`
+   new-release: {extends: '.semantic-release:stable'}
 
    # Create the prereleases versions on `$TESTING_BRANCH`
-   # update `release.config.js` variable `testingBranch`
-   testing-prerelease:
-     extends:
-       - .semantic-release:testing
+   # update `release.config.js` variable `betaBranch`
+   testing-prerelease: {extends: '.semantic-release:testing'}
 
    # Avoid regression by merging all pre-release fixes to `$DEV_BRANCH`
-   merge-to-dev:
-     stage: release
-     extends: .on-release-tag
-     # We use whatever image that has git
-     image: 'hub.eole.education/eole/commitlint:latest'
-     script:
-       # Add `upstream` remote to push with `write_repository` token
-       # Use `${GITLAB_TOKEN}` for write permission
-       - "git remote show upstream 2> /dev/null || git remote add upstream ${CI_REPOSITORY_URL/${CI_JOB_TOKEN}/${GITLAB_TOKEN}}"
-       - 'git fetch --all'
-       - 'git checkout -b ${DEV_BRANCH} upstream/${DEV_BRANCH}'
-       - 'git merge --no-edit ${CI_COMMIT_TAG}'
-       - 'git push upstream ${DEV_BRANCH}'
-       # Remove `upstream` to avoid caching `CI_JOB_TOKEN`
-       - "git remote remove upstream"
+   merge-to-dev: {extends: '.git:merge-to', variables: {GIT_MERGE_TARGET: $DEV_BRANCH}}
 
    ## tag contribution branches with a more stable name than `git-${CI_COMMIT_SHORT_SHA}`
    tag contrib branch:
      extends:
-       - .tag-docker-image
+       - .docker:image:tag
        - .on-branches
      variables:
        # `feature/foo-bar_quux` → `feature-foo-bar-quux`
@@ -354,7 +350,7 @@ you need mostly 4 steps:
    ## dev images
    tag dev:
      extends:
-       - .tag-docker-image
+       - .docker:image:tag
        - .on-dev
      variables:
        IMAGE_TAG: dev
@@ -362,7 +358,7 @@ you need mostly 4 steps:
    ## testing images
    tag testing:
      extends:
-       - .tag-docker-image
+       - .docker:image:tag
        # After `semantic-release`
        - .on-testing-tag
      variables:
@@ -371,11 +367,11 @@ you need mostly 4 steps:
    ## stable images
    # add the `X.Y.Z` tag
    tag release:
-     extends: .tag-docker-image
+     extends: .docker:image:tag
 
    # add the `X` tag
    tag major:
-     extends: .tag-docker-image
+     extends: .docker:image:tag
      before_script:
        - export RELEASE_PREFIX=${RELEASE_PREFIX:-release/}
        - export RELEASE=${CI_COMMIT_TAG#${RELEASE_PREFIX}}
@@ -383,24 +379,26 @@ you need mostly 4 steps:
 
    # add the `X.Y` tag
    tag minor:
-     extends: .tag-docker-image
+     extends: .docker:image:tag
      before_script:
        - export RELEASE_PREFIX=${RELEASE_PREFIX:-release/}
        - export RELEASE=${CI_COMMIT_TAG#${RELEASE_PREFIX}}
        - export IMAGE_TAG=${RELEASE%.${RELEASE##*.}}
 
    tag stable:
-     extends: .tag-docker-image
+     extends: .docker:image:tag
      variables:
        IMAGE_TAG: stable
 
    tag latest:
-     extends: .tag-docker-image
+     extends: .docker:image:tag
      variables:
        IMAGE_TAG: latest
+   ...
    ```
    </details>
-2. configure [`commitlint`](#validate-commit-messages) with the [`commitlint.config.js`](commitlint.config.js)
+2. configure [`commitlint`](#validate-commit-messages) with the
+   [`.commitlintrc.yaml`](.commitlintrc.yaml)
 3. configure [`semantic-release`](#generate-release-with-semantic-version-scheme)
    1. the general configuration
       [`release.config.js`](release.config.js) (note that the
@@ -425,6 +423,7 @@ itself except providing:
 - the default branch names variables
   - `$STABLE_BRANCH` defaults to `stable`
   - `$TESTING_BRANCH` defaults to `testing`
+  - `$ALPHA_BRANCH` defaults to `alpha`
   - `$DEV_BRANCH` defaults to `dev`
 - several [hidden template
   jobs](https://docs.gitlab.com/ee/ci/yaml/yaml_optimization.html) to
@@ -435,21 +434,22 @@ itself except providing:
 To use it, just include it at the top level of your `.gitlab-ci.yml`:
 
 ```diff
---- .gitlab-ci.yml.orig 2021-12-14 11:42:36.631152773 +0100
-+++ .gitlab-ci.yml  2021-12-14 11:42:13.039315046 +0100
-@@ -1,3 +1,7 @@
+--- .gitlab-ci.yml.orig
++++ .gitlab-ci.yml
+@@ -1,4 +1,8 @@
  # -*- coding: utf-8 -*-
  # vim: ft=yaml
  ---
 +include:
-+  - project: EOLE/infra/ci-tools
++  - project: EOLE/Infra/ci-tools
 +    ref: stable
 +    file: /templates/Rules.yaml
+ ...
 ```
 
 If the rules definition is too limited for your use case, you can
 combine the raw conditions to extend them like in
-[`templates/Release/Semantic-release.yaml`](templates/Release/Semantic-release.yaml)
+[`templates/Semantic-release.yaml`](templates/Semantic-release.yaml)
 
 You can read [`templates/Rules.yaml`](templates/Rules.yaml) for the
 complete list of usable rules templates.
@@ -461,27 +461,28 @@ documentation](docs/CONTRIBUTING.md), the commit message formatting is
 important to generate release automatically with
 [`semantic-release`](#generate-release-with-semantic-version-scheme).
 
-To ensure that all the commits are correctly formatted, you just need
-to:
+To ensure that all the commits are correctly formatted, you just need to:
 
-1. the `.not-on-stable` rules template provided by the
-   [rules](#target-when-to-run-jobs) template
-2. include the
-   [`templates/Lint/Commitlint.yaml`](templates/Lint/Commitlint.yaml)
-3. be sure to have the `lint` to your current `stages` in your `.gitlab-ci.yml`
-4. configure `commitlint` by creating the [`commitlint.config.js`](commitlint.config.js) in
-   the root of your repository
+1. include [`templates/Rules.yaml`](#target-when-to-run-jobs) file to
+   define the `.not-on-stable` rules templates
+2. include the [`templates/Git.yaml`](templates/Git.yaml) file
+3. be sure to have the `lint` stage to your current `stages` in your
+   `.gitlab-ci.yml`
+4. define the `commitlint` job extending [`.git:commitlint`](templates/Git.yaml#L11-L85)
+5. configure `commitlint` by creating the
+   [`.commitlintrc.yaml`](.commitlintrc.yaml) in the root of your
+   repository
 
 ```diff
---- .gitlab-ci.yml.orig 2021-12-14 11:47:56.645304805 +0100
-+++ .gitlab-ci.yml      2021-12-14 11:47:36.277406568 +0100
-@@ -5,3 +5,16 @@
-   - project: EOLE/infra/ci-tools
+--- .gitlab-ci.yml.orig
++++ .gitlab-ci.yml
+@@ -5,4 +5,17 @@
+   - project: EOLE/Infra/ci-tools
      ref: stable
      file: /templates/Rules.yaml
-+  - project: EOLE/infra/ci-tools
++  - project: EOLE/Infra/ci-tools
 +    ref: stable
-+    file: /templates/Lint/Commitlint.yaml
++    file: /templates/Git.yaml
 +
 +
 +stages:
@@ -491,7 +492,8 @@ to:
 +###############################################################################
 +# `lint` stage: `commitlint`
 +###############################################################################
-+# the `commitlint` is defined in `templates/Lint/Commitlint.yaml` included before
++commitlint: {extends: '.git:commitlint'}
+ ...
 ```
 
 #### Generate release with semantic version scheme
@@ -499,26 +501,30 @@ to:
 Before enabling the automatic release creation, you should enable [`commitlint`](#Validate-commit-messages).
 
 To setup [`semantic-release`](https://github.com/semantic-release/),
-you need:
+you need to:
 
-1. the [rules](#target-when-to-run-jobs) template included
+1. include [`templates/Rules.yaml`](#target-when-to-run-jobs) file to
+   define the `.on-stable` and `.on-testing` rules template
 2. include the
-   [`templates/Release/Semantic-release.yaml`](templates/Release/Semantic-release.yaml)
-3. be sure to have the `release` stage to your current `stages` in your `.gitlab-ci.yml`
-4. configure `semantic-release`:
+   [`templates/Semantic-release.yaml`](templates/Semantic-release.yaml) file
+3. be sure to have the `release` stage to your current `stages` in
+   your `.gitlab-ci.yml`
+4. define the `new-release` job extending [`.semantic-release:stable`](templates/Semantic-release.yaml#L17-L81)
+5. define the `testing-prerelease` job extending [`.semantic-release:testing`](templates/Semantic-release.yaml#L84-L144)
+6. configure `semantic-release`:
    1. [`release.config.js`](release.config.js)
    2. [`release-rules.js`](release-rules.js)
 
 ```diff
---- .gitlab-ci.yml.orig 2021-12-14 11:51:49.984245841 +0100
-+++ .gitlab-ci.yml  2021-12-14 11:51:29.196333335 +0100
-@@ -8,13 +8,27 @@
-   - project: EOLE/infra/ci-tools
+--- .gitlab-ci.yml.orig
++++ .gitlab-ci.yml
+@@ -8,14 +8,29 @@
+   - project: EOLE/Infra/ci-tools
      ref: stable
-     file: /templates/Lint/Commitlint.yaml
-+  - project: EOLE/infra/ci-tools
+     file: /templates/Git.yaml
++  - project: EOLE/Infra/ci-tools
 +    ref: stable
-+    file: /templates/Release/Semantic-release.yaml
++    file: /templates/Semantic-release.yaml
 
 
  stages:
@@ -529,18 +535,19 @@ you need:
  ###############################################################################
  # `lint` stage: `commitlint`
  ###############################################################################
- # the `commitlint` is defined in `templates/Lint/Commitlint.yaml` included before
+ commitlint: {extends: '.git:commitlint'}
 +
 +
 +###############################################################################
-+# `release` stage: `semantic-release`, `testing-prerelease`,
++# `release` stage: `new-release`, `testing-prerelease`
 +###############################################################################
-+# the `semantic-release` is defined in `templates/Release/Semantic-Release.yaml`
++# Create the release versions on `$STABLEE_BRANCH`
++new-release: {extends: '.semantic-release:stable'}
 +
 +# Create the prereleases versions on `$TESTING_BRANCH`
-+testing-prerelease:
-+  extends:
-+    - .semantic-release:testing
++# update `release.config.js` variable `betaBranch`
++testing-prerelease: {extends: '.semantic-release:testing'}
+ ...
 ```
 
 #### Build and tag docker images
@@ -551,7 +558,7 @@ templates to build and tag docker images.
 ##### Building images
 
 The [`templates/Docker.yaml`](templates/Docker.yaml) defines
-[`.build-docker-image`](templates/Docker.yaml#L4-54) job template
+[`.docker:image:build`](templates/Docker.yaml#L11-L84) job template
 which, by default, build the container image and push it to
 `${CI_REGISTRY}` for all branches except `$STABLE_BRANCH`.
 
@@ -561,19 +568,20 @@ does not require to enable docker-in-docker privileged mode.
 
 The simplest use of this template require 4 elements:
 
-1. the [rules](#target-when-to-run-jobs) template included
+1. include [`templates/Rules.yaml`](#target-when-to-run-jobs) file to
+   define the `.not-on-stable` and `.on-release-tag` rules template
 2. include the [`templates/Docker.yaml`](templates/Docker.yaml) template
 3. be sure to have the `build` stage to your current `stages` in your `.gitlab-ci.yml`
-4. extends the `.build-docker-image` template to define the build job
+4. extends the [`.docker:image:build`](templates/Docker.yaml#L11-L84) template to define the build job
 
 ```diff
---- .gitlab-ci.yml.orig 2021-12-14 11:53:19.627880842 +0100
-+++ .gitlab-ci.yml  2021-12-14 11:54:50.483528896 +0100
+--- .gitlab-ci.yml.orig
++++ .gitlab-ci.yml
 @@ -11,12 +11,20 @@
-   - project: EOLE/infra/ci-tools
+   - project: EOLE/Infra/ci-tools
      ref: stable
-     file: /templates/Release/Semantic-release.yaml
-+  - project: EOLE/infra/ci-tools
+     file: /templates/Semantic-release.yaml
++  - project: EOLE/Infra/ci-tools
 +    ref: stable
 +    file: /templates/Docker.yaml
 
@@ -590,8 +598,8 @@ The simplest use of this template require 4 elements:
 
  ###############################################################################
  # `lint` stage: `commitlint`
-@@ -24,6 +32,28 @@
- # the `commitlint` is defined in `templates/Lint/Commitlint.yaml` included before
+@@ -24,6 +32,33 @@
+ commitlint: {extends: '.git:commitlint'}
 
 
 +###############################################################################
@@ -601,9 +609,9 @@ The simplest use of this template require 4 elements:
 +# The build is done:
 +# - for contribution branches
 +# - for `$DEV_BRANCH`
-+# - on release tags after the application versions are updated by `semantic-release`
-+build-docker:
-+  extends: .build-docker-image
++# - on release tags (stable and testing) after the application
++#   versions are updated by `semantic-release`
++.build-docker-rules:
 +  rules:
 +    # The ordering is CRITICAL
 +    - !reference [.rules-map, not-on-schedule]
@@ -615,16 +623,22 @@ The simplest use of this template require 4 elements:
 +    - !reference [.rules-map, not-on-semantic-release-commit]
 +    - !reference [.rules-map, on-branch]
 +
++build-docker:
++  extends:
++    - .docker:image:build
++    - .build-docker-rules
++
 +
  ###############################################################################
- # `release` stage: `semantic-release`, `testing-prerelease`,
+ # `release` stage: `new-release`, `testing-prerelease`
  ###############################################################################
 ```
 
 ##### Tagging docker images
 
-By default, the [`.tag-docker-image`](templates/Docker.yaml#L56-104) job template works on the release
-tag only to create the docker tag `X.Y.Z`.
+By default, the [`.docker:image:tag`](templates/Docker.yaml#L92-L161)
+job template works on the release tag only to create the docker tag
+`X.Y.Z`.
 
 In a typical release cycle, you want to create the following tags:
 
@@ -640,38 +654,38 @@ In a typical release cycle, you want to create the following tags:
   - `release` tag with the full semantic version
   - `latest`/`stable` point to the latest stable image
 
-To be used, you need:
+To be used, you need to:
 
-1. the `.not-on-stable` rules template provided by the
-   [rules](#target-when-to-run-jobs) template
+1. include [`templates/Rules.yaml`](#target-when-to-run-jobs) file to
+   define the rules template
 2. include the [`templates/Docker.yaml`](templates/Docker.yaml)
    template
 1. be sure to have the `release` stage to your current `stages` in
    your `.gitlab-ci.yml`
-2. extends the `.tag-docker-image` template to create as many tagging
+2. extends the [`.docker:image:tag`](templates/Docker.yaml#L92-L161) template to create as many tagging
    jobs as required for your release cycle
 
 ```diff
---- .gitlab-ci.yml.orig 2021-12-14 11:58:55.434649075 +0100
-+++ .gitlab-ci.yml  2021-12-14 12:00:21.410358359 +0100
-@@ -54,7 +54,7 @@
+--- .gitlab-ci.yml.orig
++++ .gitlab-ci.yml
+@@ -60,7 +60,7 @@
 
 
  ###############################################################################
--# `release` stage: `semantic-release`, `testing-prerelease`,
+-# `release` stage: `semantic-release`, `testing-prerelease`
 +# `release` stage: `semantic-release`, `testing-prerelease`, `tag *`
  ###############################################################################
- # the `semantic-release` is defined in `templates/Release/Semantic-Release.yaml`
-
-@@ -62,3 +62,60 @@
- testing-prerelease:
-   extends:
-     - .semantic-release:testing
+ # Create the release versions on `$STABLEE_BRANCH`
+ new-release: {extends: '.semantic-release:stable'}
+@@ -68,4 +68,61 @@
+ # Create the prereleases versions on `$TESTING_BRANCH`
+ # update `release.config.js` variable `betaBranch`
+ testing-prerelease: {extends: '.semantic-release:testing}
 +
 +## tag contribution branches with a more stable name than `git-${CI_COMMIT_SHORT_SHA}`
 +tag contrib branch:
 +  extends:
-+    - .tag-docker-image
++    - .docker:image:tag
 +    - .on-branches
 +  variables:
 +    # `feature/foo-bar_quux` → `feature-foo-bar-quux`
@@ -680,7 +694,7 @@ To be used, you need:
 +## dev images
 +tag dev:
 +  extends:
-+    - .tag-docker-image
++    - .docker:image:tag
 +    - .on-dev
 +  variables:
 +    IMAGE_TAG: dev
@@ -688,7 +702,7 @@ To be used, you need:
 +## testing images
 +tag testing:
 +  extends:
-+    - .tag-docker-image
++    - .docker:image:tag
 +    # After `semantic-release`
 +    - .on-testing-tag
 +  variables:
@@ -697,11 +711,11 @@ To be used, you need:
 +## stable images
 +# add the `X.Y.Z` tag
 +tag release:
-+  extends: .tag-docker-image
++  extends: .docker:image:tag
 +
 +# add the `X` tag
 +tag major:
-+  extends: .tag-docker-image
++  extends: .docker:image:tag
 +  before_script:
 +    - export RELEASE_PREFIX=${RELEASE_PREFIX:-release/}
 +    - export RELEASE=${CI_COMMIT_TAG#${RELEASE_PREFIX}}
@@ -709,30 +723,20 @@ To be used, you need:
 +
 +# add the `X.Y` tag
 +tag minor:
-+  extends: .tag-docker-image
++  extends: .docker:image:tag
 +  before_script:
 +    - export RELEASE_PREFIX=${RELEASE_PREFIX:-release/}
 +    - export RELEASE=${CI_COMMIT_TAG#${RELEASE_PREFIX}}
 +    - export IMAGE_TAG=${RELEASE%.${RELEASE##*.}}
 +
 +tag stable:
-+  extends: .tag-docker-image
++  extends: .docker:image:tag
 +  variables:
 +    IMAGE_TAG: stable
 +
 +tag latest:
-+  extends: .tag-docker-image
++  extends: .docker:image:tag
 +  variables:
 +    IMAGE_TAG: latest
+ ...
 ```
-
-#### Select the runner to run the CI pipelines
-
-Selecting CI runners is done with tags like done globally in
-[`templates/Runners/eole-docker.yaml`](templates/Runners/eole-docker.yaml)
-or
-[`templates/Runners/apps.education-docker.yaml`](templates/Runners/apps.education-docker.yaml)
-using the [`default:tags`](https://docs.gitlab.com/ee/ci/yaml/#tags)
-in your own `.gitlab-ci.yml`.
-
-
-- 
GitLab