By default, the source of the merge is `${CI_COMMIT_TAG}` and the
target must be defined by the `.gitlab-ci.yml` job using this
template.

* docs/GETTING-STARTED.md: new section to document `.git:merge-to`
  template job.

* templates/Git.yaml: new `.git:merge-to` template job to merge a
  reference into a target branch.

Building a docker image is now done by `.docker:image:build` job
template.

Tagging a docker image is now done by `.docker:image:tag` job
template.

We keep the previous job templates for backward compatibility.

* templates/Docker.yaml: new `.docker:image:build` and
  `.docker:image:tag` job templates.

Using `semantic-release` require the users to include
`templates/Semantic-release.yaml` and `extends` the `.semantic-release:*`
job templates.

We keep `templates/Release/Semantic-release.yaml` for backward
compatibility.

* templates/Semantic-release.yaml: new `semantic-release` related job
  templates

* templates/Lint/Commitlint.yaml: define `semantic-release` with the
  `.semantic-release:stable` job template for backward compatibility.

Using `commitlint` require the users to include `templates/Git.yaml`
and `extends` the `.git:commitlint` job template.

We keep `templates/Lint/Commitlint.yaml` for backward compatibility.

* templates/Git.yaml: new git related job templates

* templates/Lint/Commitlint.yaml: define `commitlint` with the
  `.git:commitlint` job template for backward compatibility.

* .commitlintrc.yaml: move from JS to YAML.

By default, a `semantic-release` job is created for `$STABLE_BRANCH`
and you can create jobs for `$TESTING_BRANCH` and `$DEV_BRANCH` by
extending the `.semantic-release:testing` and `.semantic-release:dev`
template jobs.

New `.on-testing-with-semantic-release-config` and
`.on-dev-with-semantic-release-config` rules.

Create a new `.semantic-release:stable` template job and use it for
the default `semantic-release` job.

The previous `.on-release-tag` match everything starting with
`release/` and so prerelease tags like `release/X.Y.Z-testing` or
`release/X.Y.Z-dev`.

When doing prerelease, we want to avoid updating stable tags, we
restrict the match for release tags and add specific rules to match
`testing` and `dev` tags.

Some users may requires to pass kaniko arguments to set, for example,
some build args required by the Dockerfile.

* templates/Docker.yaml: add `KANIKO_ARGS` optional variable
  overridable by users and pass it to executor command line.

Verify formatting of all commit messages in the range
`$BASE_BRANCH..$CI_COMMIT_SHA`.

USAGE
=====

include:
  - project: EOLE/infra/ci-tools
    ref: stable
    file: /templates/Rules.yaml
  - project: EOLE/infra/ci-tools
    ref: stable
    file: /templates/Lint/Commitlint.yaml

stages:
  - lint

OPTIONAL VARIABLES
==================

- `BASE_BRANCH`: name of the referrence branch, defaults to
  `${CI_DEFAULT_BRANCH}`
- `COMMITLINT_IMAGE`: name of the `commitlint` docker image to use

REQUIREMENTS
============

- The `.not-on-stable` rules template
- A `lint` stage must be present in your pipeline or it must be
  overriden by the extending job to feet your need.

USED CI VARIABLES
=================

- `CI_COMMIT_SHA`
- `CI_DEFAULT_BRANCH`

Users can override the variable `BASE_BRANCH` in their
`.gitlab-ci.yml` to select the starting point of the logs to
validate.

Users can override the variable in their `.gitlab-ci.yml` to select
another docker image.

There is no need to add an upstream repository to access
`${CI_DEFAULT_BRANCH}` we just neet to fetch all references from
`origin`.

Avoid the use of `before_script` and `after_script` for users of the
job to be able to extend it with them.

The previous rules template set did not permit to combine rules easily
in user jobs.

Using a single hash of individual rules permit to reference them more
clearly. It avoids duplicated conditionnals in the current rules set
and marke it easier to combine them in user jobs, with some
limitations[1].

* templates/Rules.yaml: define the `.rules-map` hash of individual
  rules and reference them in rules templates

* templates/Release/Semantic-release.yaml: use the `.rules-map`
  directly to reduce the conditionnal duplication

Closes #3

Footnotes:
[1]  https://forum.gitlab.com/t/add-conditions-to-rules-array-merged-with-reference/62600

Gitlab does not permit to easily add pattern to skip CI pipelines
based on commit messages[1].

* templates/Rules.yaml: exclude commits with message matching some
  variations around `draft` and `wip`.

Closes: #2

Footnotes:
[1]  https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/pipeline/chain/skip.rb

Closes #1

* templates/Release/Semantic-release.yaml: use
  `semantic-release-gitlab` image.

We want to tag images based on the different steps of the release
cycle:

- `dev` images where developpement is integrated
- `testing` images where releases are stabilised
- `stable` images when the release is done
  - `major` tag with only the first digit of the semantic version,
    this tag will always point to the latest release of the major
    version
  - `minor` tag with only the first 2 digits of the semantic version,
    this tag will always point to the latest release of the minor
    version
  - `release` tag with the full semantic version
  - `latest`/`stable` point to the latest stable image

Define `.tag-docker-image` template used by `*-docker-tag` jobs It tag
the `${IMAGE_NAME}:${SOURCE_TAG}` with the tag `${IMAGE_TAG}`

USAGE
=====

foo-docker-tag-devel:
  extends: .tag-docker-image
  variables:
    IMAGE_TAG: 'devel'

REQUIREMENTS
============

- A `release` stage must be present in your pipeline or it must be
  overriden by the extending job to feet your need.
- The `.not-on-stable` rules template

OPTIONAL VARIABLES
==================

- `IMAGE_NAME`: defaults to `${CI_JOB_NAME}` with any suffix
  `-docker-tag*` removed
- `SOURCE_TAG`: source image tag to retag, defaults to
  `git-${CI_COMMIT_SHORT_SHA}`
- `IMAGE_TAG`: image tag, defaults to `${CI_COMMIT_TAG}` with prefix
  `RELEASE_PREFIX` removed
- `RELEASE_PREFIX`: prefix of the `RELEASE`, defaults to `release/`

USED CI VARIABLES
=================

- `CI_REGISTRY`
- `CI_REGISTRY_USER`
- `CI_REGISTRY_PASSWORD`
- `CI_REGISTRY_IMAGE`

Define `.build-docker-image` template used by `*-docker-build` jobs It
build the container image and push it to `${CI_REGISTRY}`

USAGE
=====

foo-docker-build:
  extends: .build-docker-image
  variables:
    DOCKERFILE: Some-specific.Dockerfile
    IMAGE_TAG: $CI_COMMIT_REF_SLUG

REQUIREMENTS
============

- A `build` stage must be present in your pipeline or it must be
  overriden by the extending job to feet your need.
- The `.not-on-stable` rules template

OPTIONAL VARIABLES
==================

- `IMAGE_NAME`: defaults to `${CI_JOB_NAME}` with any suffix
  `-docker-build*` removed
- `DOCKERFILE`: defaults, in order
   - to value set by the user
   - to `Dockerfile.${IMAGE_NAME}` if the file exists
   - to `Dockerfile` if the file exists
- `IMAGE_TAG`: defaults to `git-${CI_COMMIT_SHORT_SHA}`

USED CI VARIABLES
=================

- `CI_REGISTRY`
- `CI_REGISTRY_USER`
- `CI_REGISTRY_PASSWORD`
- `CI_REGISTRY_IMAGE`

Create new release when merge requests are merged into the
`$STABLE_BRANCH` branch.

* templates/Release/Semantic-release.yaml: run `semantic-release` with
  the latest EOLE container for `$STABLE_BRANCH` branch if one of its
  configuration is present.

* .gitlab-ci.yml: execute a new stage `release` for
  `semantic-release`.

* release.config.js: create `docs/CHANGELOG.md` and publish new
  releases on Gitlab.
  Mangle commits to have links for users, issues and commits id.

* release-rules.js: create semantic version update rules based on
  `docs/CONTRIBUTING.md`.

This make a better distinction between `stable` software and software
deployed in production.

We define 3 branches:
- `dev`: new developped features are integrated here, this is the
  default branch
- `testing`: is a fork of `dev` when we want to prepare the next
  release, this is the branch from where release bugfixes are derived
  and merged back
- `stable`: is where the `testing` branch is merged to produce a new
  release

We define rules to match somewhate a git-flow style workflow to
activate jobs:

- `.not-on-prod`: on all branches except production

- `.on-branches` : on supporting branches, i.e. everything except
  production and developpment

- `.on-dev`: on developpment branch only

- `.on-prod`: on production branch only

- `.on-release-tag`: on the release tag only

We always exclude pipeline triggered from schedule.

* templates/Rules.yaml: define the new rules templates.

* templates/Lint/Commitlint.yaml (commitlint): execute on all branch
  except production.

* templates/Lint/Commitlint.yaml (commitlint): use
  `$CI_DEFAULT_BRANCH` as base to calculate the list of commits to check.

This will permit other projects to
[include](https://docs.gitlab.com/ee/ci/yaml/#include) the defined
templates

The `templates/Rules.yaml` must be included and jobs will `extends`
the templates depending at which moment they must be executed.