docs: detailed info about semantic-release integration with other TBC templates

3. Don't forget to escape special characters (ex: `$` -> `$$`).

4. You can also manage secrets using Vault variant

## Using semantic-release with other to-be-continuous templates

The semantic-release template has been designed to interoperate gracefully with release-capable to-be-continuous templates.

Unfortunaltely, there can't be one single configuration that fits all needs.

Instead, the semantic-release template configuration will have to be adapted to your case.

There are actually 2 questions that will determine the required configuration:

1. which [Delivery Mode](https://to-be-continuous.gitlab.io/doc/understand/#delivery-modes) are you using in your project?

    * _Application Deployment_ mode should trigger the release directly from your production branch (`main` or `master` by default),

    * _Software Distribution_ mode should trigger the release through a tag pipeline.

2. does the release involve **changing files in your repository** (and therefore creating a Git commit)?

    * that will be the case if you use plugins such as [@semantic-release/changelog](https://github.com/semantic-release/changelog) or the [semantic-release-replace](https://github.com/jpoehnelt/semantic-release-replace-plugin)

### Case 1: _Application Deployment_ mode

As said previously, if you're using the _Application Deployment_ delivery mode in your project, you should trigger the release directly from your production branch (`main` or `master` by default).

In that case you'll need to:

1. enable the [semantic-release info job](#semantic-release-info-job),

   * by setting `info-on` / `SEMREL_INFO_ON` to `prod` (or any suitable non-empty value)

2. disable the [semantic-release job](#semantic-release-job),

   * by setting `release-disabled` / `SEMREL_RELEASE_DISABLED` to `true`

3. make sure the other template(s) provide a semantic-release integration to perform the release from the semantic-release info job. 

   Templates supporting it:

   * Docker,

   * Helm,

   * Maven,

   * Python,

   * S2I.

### Case 2: _Software Distribution_ mode without any Git commit

This is the easiest case as nothing specific has to be done to address it:

* by default the semantic-release will analyse each commit on your production branch, and will possibly create a Git tag (but no Git commit) if it determined a release has to be performed,

* the Git tag will trigger a tag pipeline during which every to-be-continuous template will take care of publishing its versioned package (using the Git tag as the version) to an appropriate packages repository.

### Case 3: _Software Distribution_ mode with a Git commit

This case will occur if you configure semantic-release to modify one or several files in your Git repository (ex: `pom.xml`, `pyproject.toml`, `CHANGELOG.md`, `README.md`...)

In that case, when semantic-release determines a release is required, it will:

* modify the files,

* create a Git commit with the changes,

* create a Git tag with the next release version,

* push the commit + the tag.

Problem: by default, semantic-release creates a Git commit with comment `chore(release): release ${nextRelease.version} [skip ci]`.

The `[skip ci]` part prevents GitLab from triggering the tag pipeline, therefore preventing other to-be-continuous templates from publishing their versioned packages.

To fix this, you'll have to override the default semantic-release Git commit comment in order not to prevent the tag pipeline from being triggered.

With this done:

* the semantic-release will analyse each commit on your production branch, and will possibly create a Git tag if it determined a release has to be performed,

* the Git tag will trigger a tag pipeline during which every to-be-continuous template will take care of publishing its versioned package (using the Git tag as the version) to an appropriate packages repository.

#### How to override the Git commit comment

In most cases it is recommended to use `chore(release): release ${nextRelease.version} [skip ci on prod]` (the `[skip ci on prod]` part prevents GitLab from triggering the pipeline on your production branch only, **but not the tag pipeline**).

If you're configuring semantic-release with a configuration file in your repository, then the Git commit message has to be configured in the [@semantic-release/git](https://github.com/semantic-release/git#message) plugin section.

Here is a configuration example that auto-generates the changelog file, and also replaces the project version in the `pyproject.toml` using the [semantic-release-replace](https://github.com/jpoehnelt/semantic-release-replace-plugin) plugin:

```yaml

plugins:

  - '@semantic-release/commit-analyzer'

  - '@semantic-release/release-notes-generator'

  - '@semantic-release/gitlab'

  # generates the CHANGELOG.md

  - '@semantic-release/changelog'

  # emulates bumpversion (replaces version in pyproject.toml)

  - - semantic-release-replace-plugin

    - replacements:

        - files:

            - pyproject.toml

          from:

            - ^version *= *"\d+\.\d+\.\d+"

          to: 'version = "${nextRelease.version}"'

          countMatches: true

  # git commit/push modified files (CHANGELOG.md & pyproject.toml)

  - - '@semantic-release/git'

    - assets:

        - '*.md'

        - '*.toml'

      # the commit MUST trigger a pipeline on tag (to perform publish jobs)

      # can be skipped on prod branch

      message: 'chore(release): release ${nextRelease.version} [ci skip on prod]'

branches:

  - main

  - master

tagFormat: '${version}'

```

If you're not configuring semantic-release with a configuration file (but using default configuration provided by the template), then the Git commit message can be configured with the `commit-message` / `SEMREL_COMMIT_MESSAGE` input / variable:

```yaml

variables:

  # the '$' has to be doubled to prevent GitLab from expanding it as a variable

  SEMREL_COMMIT_MESSAGE: 'chore(release): release $${nextRelease.version} [ci skip on prod]'

```

## Variants

The Docker template can be used in conjunction with template variants to cover specific cases.

The semantic-release template can be used in conjunction with template variants to cover specific cases.

### Vault variant