docs: improve integration with other TBC templates chapter

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.

Unfortunaltely, there isn't 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:

### 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).

When using the _Application Deployment_ delivery mode in your project, the release should be triggered directly from the 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),<br/>

   _this is the job that will provide next release information to the other template(s)_

   * 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 `info-on` input / `SEMREL_INFO_ON` variable to `prod` (or any suitable non-empty value)

2. disable the [semantic-release job](#semantic-release-job),<br/>

   _the release will be handled by other template(s) directly from the production branch_

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

   * by setting `release-disabled` input / `SEMREL_RELEASE_DISABLED` variable 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,

* 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]`.\

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

:information_source: The `[skip ci]` part is problematic as it 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.

#### How to override the Git commit comment

In most cases it is recommended to use `chore(release): release ${nextRelease.version} [skip ci on prod]` as message template.\

:information_source: the `[skip ci on prod]` part prevents GitLab from triggering the pipeline on your production branch only, **but not the tag pipeline**.

In most cases it is recommended to use `chore(release): ${nextRelease.version} [skip ci on prod]` as message template.\

:information_source: the important part is `[skip ci on prod]` that prevents GitLab from triggering the pipeline on your production branch only, **but not the tag pipeline**.

#### Using a configuration file

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:

Here is a `.releaserc.yaml` 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:

  # GitLab support

  - '@semantic-release/gitlab'

  # analyses the Git commits

  - '@semantic-release/commit-analyzer'

  # generates the release note from the Git commit messages

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

  - '@semantic-release/gitlab'

  # generates the CHANGELOG.md

  # generates the CHANGELOG.md file

  - '@semantic-release/changelog'

  # emulates bumpversion (replaces version in pyproject.toml)

  # emulates bumpversion (replaces 'version' in pyproject.toml)

  - - semantic-release-replace-plugin

    - replacements:

        - files:

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

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

          countMatches: true

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

  # git commit/push modified files

  - - '@semantic-release/git'

    - assets:

        - '*.md'

        - '*.toml'

        - 'CHANGELOG.md'

        - 'pyproject.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]'

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

branches:

  - main

  - master

#### Using implicit configuration

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

If you're not configuring semantic-release with a configuration file (but using implicit configuration provided by the template), then the Git commit message can be configured with the `commit-message` input / `SEMREL_COMMIT_MESSAGE` 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]'

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

```

## Variants