From 870b21ccc9d6bc5af7011faec0824830e799c546 Mon Sep 17 00:00:00 2001
From: Daniel Speicher <daniel.speicher@lakedrops.com>
Date: Thu, 25 Jul 2024 15:37:08 +0200
Subject: [PATCH] Document stages and jobs.

---
 docs/gitlab/drupal/index.md | 47 ++++++++++++++++++++++++++++++++++---
 1 file changed, 44 insertions(+), 3 deletions(-)

diff --git a/docs/gitlab/drupal/index.md b/docs/gitlab/drupal/index.md
index 2a8bbe4..5539cb5 100644
--- a/docs/gitlab/drupal/index.md
+++ b/docs/gitlab/drupal/index.md
@@ -21,8 +21,8 @@ allow to run very powerful pipelines which contain the following stages:
 - [validate](#validate)
 - [test (predefined)](#test)
 - [deploy (predefined)](#deploy)
-- finalize
-- release
+- [finalize](#finalize)
+- [release](#release-stage)
 - .post (predefined)
 
 We have a predefined `execute` job called `LakeDrops`, which looks like this:
@@ -61,7 +61,9 @@ available for configuration.
 The following chapters describes all stages and their jobs. The files:
 
 -  [lakedrops.yml](https://gitlab.lakedrops.com/gitlab-ci-cd/drupal/-/blob/main/lakedrops.yml?ref_type=heads).
+-  [tests/lakedrops.yml](https://gitlab.lakedrops.com/gitlab-ci-cd/drupal/-/blob/main/tests/lakedrops.yml?ref_type=heads).
 -  [test_deploy.yml](https://gitlab.lakedrops.com/gitlab-ci-cd/drupal/-/blob/main/test-and-deploy.yml?ref_type=heads).
+-  [check4updates.yml](https://gitlab.lakedrops.com/gitlab-ci-cd/drupal/-/blob/main/check4updates.yml?ref_type=heads).
 
 ### .pre
 To prepare and check, if the environment is good to go, we have a `.pre` stage, which contains the
@@ -209,7 +211,6 @@ The job stores the artefacts in `check4updates`.
 
 
 
-
 Rules, when the job should run:
 
 - `$CHECKUPDATES` is set
@@ -648,6 +649,27 @@ This job simply stops and removes the docker container, which are started for th
 
 `docker compose down`
 
+### Release Stage
+
+This stage is responsible for creating a new release.
+
+#### Release Job
+
+This job extends the internal job [.merge](#merge).
+
+Rules, when the job should run:
+
+- `$CI_COMMIT_MESSAGE` contains `CREATE_RELEASE`
+- we are on the `develop` branch
+
+Rules, when the job must not run:
+
+- if the reference is a `tag`
+- `$CI_COMMIT_MESSAGE` contains `Merge tag`
+- if it is triggered by config auto export (CAE)
+- `$CHECKUPDATES` is set
+- `$TRIGGERTASK` is set
+
 
 ### Internal Stages
 
@@ -676,6 +698,25 @@ The following points will be prepared for [Composer](https://getcomposer.org/):
 - the configuration `audit.abandoned`, depend on `$IGNORE_COMPOSER_ABANDONED_AUDIT`
 - unsupported module versions, which are allowed to use
 
+#### .merge
+
+First we have to do some preparation. This is done in the `before_script` section.
+
+- [.prepareaccess](#prepareaccess)
+
+We start a docker image for php with the specifies versions:
+
+- `PHP_MAJOR_VERSION`
+- `PHP_MINOR_VERSION`
+
+We create a clean directory and clone the git project `$CI_PROJECT_PATH`
+for branch `$SOURCE_BRANCH` from `$CI_SERVER_HOST` right into it.
+
+After that we execute the [merge](https://gitlab.lakedrops.com/docker/gitlab-drupal-ci/-/blob/main/bin/merge?ref_type=heads) 
+script, which does a few checks and use the `gitlab` tool to merge.
+
+Finally, we remove the directory we created above.
+
 #### .retry-for-system-issues
 
 #### .cache_default
-- 
GitLab