Merge branch 'feat/include_branching_template' into 'master'

docs(Templates): a branching script

See merge request gilden/ci/gitlab-ci-templates!14

documentation/chapters/pipelines/update-version-pipeline.adoc

@@ -105,3 +105,96 @@ image::Release-Docker-Image-Pipeline.png[]
 ----
 include::{sourcedir}/update-version-pipeline.gitlab-ci.yml[]
 ----
+
+== Usage with release branches
+
+The `update version template` can be used to create a pipeline which supports releasing of artifacts from a release branch instead of the master branch. The https://gitlab.exxcellent.de/gilden/ci/exxcellent-increase-version-tool[exxcellent-versioning-tool] takes care of creating the next reasonable version numbers.
+
+If you want to realise this topic you can use the template the following way:
+
+.gitlab-ci.yml
+[source, yaml]
+----
+stages:
+  - release
+
+include:
+  - project: 'gilden/ci/gitlab-ci-templates'
+    ref: 'master'
+    file:
+    - 'release-template.gitlab-ci.yml'
+
+# Creates next major prerelease on master (e.g.: 2.0.0-rc.1 --> 3.0.0-rc.1)
+a.major-prerelease:
+  extends: .release-template
+  variables:
+    BUMP_VERSION: "major prerelease"
+    MODE: "bump"
+
+# Creates next minor prerelease on master (e.g.: 2.0.0-rc.1 --> 2.1.0-rc.1)
+b.minor-prerelease:
+  extends: .release-template
+  variables:
+    BUMP_VERSION: "minor prerelease"
+    MODE: "bump"
+
+# Creates release on release branch (e.g.: 2.0.0-rc.1 --> 2.0.0)
+a.create-release:
+  extends: .release-template
+  variables:
+    BUMP_VERSION: "patch"
+    MODE: "next_version"
+  rules:
+    - if: $CI_COMMIT_REF_NAME =~ /^release/
+      when: manual
+    - when: never
+
+# Creates next prerelease on release branch (e.g.: 2.0.0 --> 2.0.1-rc.1 or 2.0.0-rc.1 --> 2.0.1-rc.2)
+b.create-prerelease:
+  extends: .release-template
+  variables:
+    BUMP_VERSION: "prerelease"
+    MODE: "next_version"
+  rules:
+    - if: $CI_COMMIT_REF_NAME =~ /^release/
+      when: manual
+    - when: never
+
+----
+
+.release.gitlab-ci.yml
+[source, yaml]
+----
+stages:
+  - set-version
+  - push-tag-and-version
+  - release
+
+include:
+  - project: 'gilden/ci/gitlab-ci-templates'
+    ref: 'master'
+    file:
+    - '/pipelines/update-version-pipeline.yml'
+    - 'push-image.yml'
+
+# This is optional
+push-docker-image:
+  extends: .publish-image-kaniko
+  stage: release
+  # You only need NEED if you use a artifact from your parent pipeline to build the image
+  needs:
+    - pipeline: $PARENT_PIPELINE_ID
+      job: Build
+    - job: increase-version
+    - job: push-tag-and-version
+  rules:
+    - when: always
+  before_script:
+    - "[ -f ./version ] && export LATEST_VERSION=$(cat ./version)"
+    - export PARSED_VERSION=$(echo $LATEST_VERSION | sed -r 's/\+/_/g') # Replace + sign since this is not valid in a docker tag
+    - export IMAGE_NAME=$CI_REGISTRY_IMAGE:$PARSED_VERSION
+----
+
+More information on this topic and a more detailed instructions can be found in our https://gitlab.exxcellent.de/gilden/ci/exxcellent-branching-template[exxcellent-branching-template].
+
+