Document stages and jobs.

docs/gitlab/drupal/index.md

@@ -105,11 +105,70 @@ This stage is currently not officially used.
 
 This stage executes the build itself.
 
+### Build Prod
+
+This stage is responsible for building the production website, which we want to finally deploy.
+
+#### Build Prod Site
+
+First we have to do some preparation. This is done in the `before_script` section.
+
+- [.prepareaccess](#prepareaccess)
+- [.preparecomposerplugins](#preparecomposerplugins)
+
+We start a docker image for php with the specifies versions:
+
+- `PHP_MAJOR_VERSION`
+- `PHP_MINOR_VERSION`
+
+In the script section we first update the environment by executing `/usr/local/bin/update-env`.
+
+After that we install the production site with `composer install` **without** the tools for development. That is pretty 
+it. We also add `drupal/core-vendor-hardening`.
+
+The entire installation is saved as a build artefact called `build-prod` where all `git` files are excluded.
+
+#### Build Prod Site NG
+
 ### Build
 
 Here, we define jobs, which build the Drupal website and does some additional checks. This stage is
 responsible for the database downloads as well.
 
+#### Build Site
+
+We start a docker image for php with the specifies versions:
+
+- `PHP_MAJOR_VERSION`
+- `PHP_MINOR_VERSION`
+
+After that, we start to build the Drupal site with [Composer](https://getcomposer.org/):
+
+Now we execute a `composer install` twice to ensure that all patches get applied correctly. After
+that we setup our own `LakeDrops` tools by `composer lakedrops:scaffold` and
+`composer lakedrops:docker4drupal`.
+
+The next step is to pull all required [Docker](https://www.docker.com/) images 
+with [Docker Compose](https://docs.docker.com/compose/) adn start the services.
+
+After everything has started, we create some directories, e.g. for styles, logs and JavaScript.
+
+The entire installation is saved as a build artefact called `build` where all `git` files are excluded.
+
+Rules, when the job should run:
+
+- the tests are enabled by `$TESTSDISABLED` == "no"
+
+#### Build Theme
+
+This job creates the required files for the styling of the website. 
+
+The following jobs must run before successfully:
+
+- [Build Prod Site](#build-prod-site)
+
+
+
 #### Download DB
 
 This job executes a script, that removes the SQL file `$]PROJECT_NAME}.sql`, if it exists already.
@@ -138,7 +197,18 @@ to dumb the current live database to the file `$]PROJECT_NAME}.sql`.
 
 The file is saved as a build artefact, which contains `$]PROJECT_NAME}.sql`.
 
-The rules are equal to [Download DB](#download-db).
+Rules, when the job must not run:
+
+- `$DISABLE_DEPLOYMENT` != "0"
+- `$DISABLE_DEPLOYMENT_LOCAL` != "0"
+- `$DBREQUIRED` == "no"
+- `$INITIALINSTALL` == "yes"
+- `$TESTSDISABLED` == "yes"
+- `$LOCALDBFILE` != "none"
+
+Rules, when the job should run:
+
+- the tests are enabled by `$DISABLE_CI_TESTS` != "1"
 
 ### Prepare
 
@@ -152,7 +222,7 @@ anchor [import_db_default](#import-db-default-anchor).
 
 The following jobs must run before successfully:
 
-- [Build Site]()
+- [Build Site](#build-site)
 - [Download DB](#download-db)
 
 Rules, when the job must not run:
@@ -169,6 +239,7 @@ Rules, when the job should run:
 - the tests are enabled by `$DISABLE_CI_TESTS` != "1"
 
 ##### Import DB Default Anchor
+
 We start a docker image for php with the specifies versions:
 
 - `PHP_MAJOR_VERSION`
@@ -178,13 +249,83 @@ A script copies the available SQL file into the PHP container, drops the current
 If the variable `SKIPCONFIGIMPORT` is `no`, a `drush config-import` gets executed as well. After that the
 `UPDATE_DB_COMMAND` gets called as well as a cache reset.
 
-#### Import DB
+#### Import DB NG
 
+This job extends `.importdbNG`, which itself defines the
+anchor [import_db_default](#import-db-default-anchor).
+
+The following jobs must run before successfully:
+
+- [Build Site](#build-site)
+- [Download DB NG](#download-db-ng)
+
+Rules, when the job must not run:
+
+- `$DISABLE_DEPLOYMENT` != "0"
+- `$DISABLE_DEPLOYMENT_LOCAL` != "0"
+- `$DBREQUIRED` == "no"
+- `$INITIALINSTALL` == "yes"
+- `$TESTSDISABLED` == "yes"
+- `$LOCALDBFILE` != "none"
+
+Rules, when the job should run:
+
+- the tests are enabled by `$DISABLE_CI_TESTS` != "1"
 
 #### Import Local DB
 
+This job extends `.importdbLocal`, which itself defines the
+anchor [import_db_default](#import-db-default-anchor).
+
+The following jobs must run before successfully:
+
+- [Build Site](#build-site)
+
+A before script is executed, which copies the `${LOCALDBFILE}` to `${PROJECT_NAME}.sql.gz` and
+unzips that file.
+
+Rules, when the job must not run:
+
+- `$DBREQUIRED` == "no"
+- `$TESTSDISABLED` == "yes"
+- `$LOCALDBFILE` != "none"
+
+Rules, when the job should run:
+
+- the tests are enabled by `$DISABLE_CI_TESTS` != "1"
+
+#### Update DB
+
+We start a docker image for php with the specifies versions:
+
+- `PHP_MAJOR_VERSION`
+- `PHP_MINOR_VERSION`
+
+If the variable `SKIPCONFIGIMPORT` is `no`, a `drush config-import` gets executed as well. 
+After that the `UPDATE_DB_COMMAND` gets called as well as a cache reset.
+
+The following jobs must run before successfully:
+
+- [Build Site](#build-site)
+
+Rules, when the job must not run:
+
+- `$DBREQUIRED` == "yes"
+- `$DBUPDREQUIRED` == "no"
+- `$INITIALINSTALL` == "yes"
+- `$TESTSDISABLED` == "yes"
+
+Rules, when the job should run:
+
+- the tests are enabled by `$DISABLE_CI_TESTS` != "1"
+
+### Internal Stages
 
+Here we have some internal stages, which cannot be executed alone. The purpose is to
+collect repeating execution.
 
+#### .prepareaccess
+#### .preparecomposerplugins
 
 ## Configuration