diff --git a/docs/gitlab/drupal/index.md b/docs/gitlab/drupal/index.md index c378463973577d80cff132ba27bbffcfc82760fb..2a8bbe4d4b7fb673ade2a03f7fae95b8c59755f8 100644 --- a/docs/gitlab/drupal/index.md +++ b/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,126 @@ The following jobs must run before successfully: - [Build Prod Site](#build-prod-site) +#### Check 4 Updates + +e start a docker image for `php` with the specifies versions: + +- `PHP_MAJOR_VERSION` +- `PHP_MINOR_VERSION` + +First we have to do some preparation. This is done in the `before_script` section. + +- [.prepareaccess](#prepareaccess) +- [.preparecomposerplugins](#preparecomposerplugins) + +The job stores the artefacts in `check4updates`. + + + + +Rules, when the job should run: + +- `$CHECKUPDATES` is set +- we are on the `develop` branch + + #### 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. + +Then 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 +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. + +Then we check for outdated packages: + +```yml +composer diagnose --no-interaction || true +composer audit --no-dev --locked --format=table +``` + +Rules, when the job must not run: + +- the commit message contains `SKIP_check4security` 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_AUDIT` == "0" + #### Download DB This job executes a script, that removes the SQL file `$]PROJECT_NAME}.sql`, if it exists already. @@ -349,6 +463,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. @@ -365,12 +482,65 @@ Rules, when the job should run: #### Test PHPUnit +This job uses [PHP Unit](../../dev_tools/test.md#unitkernelfunctional-testing) and stores the artefacts in `phpunit`. + +Rules, when the job should run: + +- the code style tests are enabled by `$DISABLE_CI_TEST_PHPUNIT` != "1" + #### Test Backstop +This job uses [Backstop](../../dev_tools/test.md#unitkernelfunctional-testing) and stores the artefacts in `backstop`. + +The following jobs must run before successfully. Some are optional, which means, if they exist, this job waits for them +to complete: + +- [Build Site](#build-site) +- [Build Theme](#build-theme) + - uses its artefacts + - optional +- [Import DB](#import-db) + - optional +- [Import DB NG](#import-db-ng) + - optional +- [Import Local DB](#import-local-db) + - optional +- [Update DB](#update-db) + - optional + +Rules, when the job should run: + +- the backstop tests are enabled by `$DISABLE_CI_TEST_BACKSTOP` != "1" + #### Test Cypress E2E +This job uses [Cypress](../../dev_tools/test.md#cypress) and stores the artefacts in `cypresse2e`. The tests +are executed in headless mode. + +The following jobs must run before successfully. Some are optional, which means, if they exist, this job waits for them +to complete: + +- [Build Site](#build-site) +- [Build Theme](#build-theme) + - uses its artefacts + - optional +- [Import DB](#import-db) + - optional +- [Import DB NG](#import-db-ng) + - optional +- [Import Local DB](#import-local-db) + - optional +- [Update DB](#update-db) + - optional +- [Test Backstop](#test-backstop) + - optional + +Rules, when the job should run: + +- the cypress tests are enabled by `$DISABLE_CI_TEST_CYPRESSE2E` != "1" + #### Internal Test Stages Every test stage needs internal reoccurring definitions. @@ -459,6 +629,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 @@ -487,6 +676,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