Document stages and jobs.

docs/gitlab/drupal/index.md

@@ -13,21 +13,21 @@ This project contains a number of pre-configured tasks for GitLab CI/CD that
 allow to run very powerful pipelines which contain the following stages:
 
 - [.pre (predefined)](#pre)
-- [validate](#validate)
 - [execute](#execute)
-- [build (predefined)](#build)
 - [buildprod](#build-prod)
+- [build (predefined)](#build)
 - [prepare](#prepare)
+- [postprocess](#postprocess)
+- [validate](#validate)
 - [test (predefined)](#test)
 - [deploy (predefined)](#deploy)
-- release
 - finalize
-- postprocess
+- release
 - .post (predefined)
 
 We have a predefined `execute` job called `LakeDrops`, which looks like this:
 
-- execute
+- [execute](#execute)
     - LakeDrops
         - [buildprod](#build-prod)
             - [Build Prod Site](#build-prod-site)
@@ -49,8 +49,8 @@ We have a predefined `execute` job called `LakeDrops`, which looks like this:
             - [Test PHPUnit](#test-phpunit)
             - [Test Backstop](#test-backstop)
             - [Test Cypress E2E](#test-cypress-e2e)
-        - finalize
-            - Shut Down Docker Project
+        - [finalize](#finalize)
+            - [Shut Down Docker Project](#shut-down-docker-project)
 
 These pre-configured tasks can easily be included into your Drupal project.
 A GitLab runner on any host can then be configured to run those pipelines. The 
@@ -163,7 +163,7 @@ responsible for the database downloads as well.
 
 #### Build Site
 
-We start a docker image for php with the specifies versions:
+We start a docker image for `php` with the specifies versions:
 
 - `PHP_MAJOR_VERSION`
 - `PHP_MINOR_VERSION`
@@ -193,12 +193,63 @@ The following jobs must run before successfully:
 
 - [Build Prod Site](#build-prod-site)
 
+#### Check 4 Updates
+
 #### Check 4 Outdated Packages
 
+We start a docker image for `php` with the specifies versions:
+
+- `PHP_MAJOR_VERSION`
+- `PHP_MINOR_VERSION`
+
+The following jobs must run before successfully. Some are optional, which means, if they exist, this job waits for them
+to complete:
+
+- [Check 4 Updates](#check-4-updates)
+    - uses its artefacts
+    - optional
+- [Build Prod Site](#build-prod-site)
+    - uses its artefacts
+    - optional
+- [Build Prod Site NG](#build-prod-site-ng)
+    - uses its artefacts
+    - optional
+- [Build Site](#build-site)
+    - uses its artefacts
+    - optional
+
+First we have to do some preparation. This is done in the `before_script` section.
+
+- [.prepareaccess](#prepareaccess)
+- [.preparecomposerplugins](#preparecomposerplugins)
+
+First we perform a `composer update` which all dependencies without the development part.
+
+The we check for outdated packages:
+
+```yml
+composer outdated --minor-only --strict --no-interaction $OUTDATED_EXTRAS
+composer outdated --patch-only --strict --no-interaction $OUTDATED_EXTRAS
+```
+
+The variable `$OUTDATED_EXTRAS` contains the ignored package like:
+`--ignore=drupal/somemodule --ignore=drupal/another`
+
+Rules, when the job must not run:
+
+- the commit message contains `SKIP_check4outdated` and `$CHECKUPDATES` != "yes"
+- the commit message contains "Merge branch 'develop' into 'main'"
+- the commit message contains "Merge branch 'release' into 'main'"
+
+Rules, when the job should run:
+
+- `$IGNORE_COMPOSER_EXTENDED_AUDIT` == "0"
+
 
 
 #### Check 4 Security Vulnerability Advisories
 
+
 #### Download DB
 
 This job executes a script, that removes the SQL file `$]PROJECT_NAME}.sql`, if it exists already.
@@ -349,6 +400,9 @@ Rules, when the job should run:
 
 - the tests are enabled by `$DISABLE_CI_TESTS` != "1"
 
+### Postprocess
+
+
 ### Test
 
 After the preparation and the setup of a Drupal database, we can execute tests. This happens in this stage.
@@ -512,6 +566,25 @@ Rules, when the job must not run:
 - `$DISABLE_DEPLOYMENT` != "0"
 - `$CI_COMMIT_BRANCH` != "main" && `$ENFORCE_DEPLOYMENT` != "1"
 
+### Finalize
+
+Here we can do cleanups and remove some garbage the build process produces.
+
+#### Shut Down Docker Project
+
+We start a docker image for php with the specifies versions:
+
+- `PHP_MAJOR_VERSION`
+- `PHP_MINOR_VERSION`
+
+The following jobs must run before successfully:
+
+- [Build Site](#build-site)
+
+This job simply stops and removes the docker container, which are started for the build by:
+
+`docker compose down`
+
 
 ### Internal Stages
 
@@ -540,6 +613,10 @@ 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
 
+#### .retry-for-system-issues
+
+#### .cache_default
+
 ## Configuration
 
 ### GitLab Runner