ci: Add comments, rename build stages

No non-cosmetic changes, just making things more accessible.

Signed-off-by: Daniel Stone <daniels@collabora.com>

.gitlab-ci.yml

@@ -1,5 +1,47 @@
-.templates_sha: &template_sha 290b79e0e78eab67a83766f4e9691be554fc4afd # see https://docs.gitlab.com/ee/ci/yaml/#includefile
+# This file uses the freedesktop ci-templates to build Weston and run our
+# tests in CI.
+# 
+# ci-templates uses a multi-stage build process. First, the base container
+# image is built which contains the core distribution, the toolchain, and
+# all our build dependencies. This container is aggressively cached; if a
+# container image matching $FDO_DISTRIBUTION_TAG is found in either the
+# upstream repo (wayland/weston) or the user's downstream repo, it is
+# reused for the build. This gives us predictability of build and far
+# quicker runtimes, however it means that any changes to the base container
+# must also change $FDO_DISTRIBUTION_TAG. When changing this, please use
+# the current date as well as a unique build identifier.
+#
+# After the container is either rebuilt (tag mismatch) or reused (tag
+# previously used), the build stage executes within this container.
+#
+# The final stage is used to expose documentation and coverage information,
+# including publishing documentation to the public site when built on the
+# main branch.
+#
+# Apart from the 'variables', 'include', and 'stages' top-level anchors,
+# everything not beginning with a dot ('.') is the name of a job which will
+# be executed as part of CI, unless the rules specify that it should not be
+# run.
+#
+# Variables prefixed with CI_ are generally provided by GitLab itself;
+# variables prefixed with FDO_ and templates prefixed by .fdo are provided
+# by the ci-templates.
+#
+# For more information on GitLab CI, including the YAML syntax, see:
+#   https://docs.gitlab.com/ee/ci/yaml/README.html
+#
+# Note that freedesktop.org uses the 'Community Edition' of GitLab, so features
+# marked as 'premium' or 'ultimate' are not available to us.
+#
+# For more information on ci-templates, see:
+#   - documentation at https://freedesktop.pages.freedesktop.org/ci-templates/
+#   - repo at https://gitlab.freedesktop.org/freedesktop/ci-templates/
 
+# Here we use a fixed ref in order to isolate ourselves from ci-templates
+# API changes. If you need new features from ci-templates you must bump
+# this to the current SHA you require from the ci-templates repo, however
+# be aware that you may need to account for API changes when doing so.
+.templates_sha: &template_sha 290b79e0e78eab67a83766f4e9691be554fc4afd # see https://docs.gitlab.com/ee/ci/yaml/#includefile
 
 include:
   # Debian container builder template
@@ -12,12 +54,15 @@ include:
     file: '/templates/ci-fairy.yml'
 
 
+# Define the build stages. These are used for UI grouping as well as
+# dependencies.
 stages:
-  - review
+  - "Merge request checks"
-  - prep
+  - "Base container"
-  - build
+  - "Build and test"
 
 
+# Base variables used for anything using a Debian environment
 variables:
   DEBIAN_PACKAGES: 'build-essential pkg-config libexpat1-dev libffi-dev libxml2-dev doxygen graphviz xmlto xsltproc docbook-xsl python3-pip python3-setuptools ninja-build'
   DEBIAN_EXEC: 'pip3 install meson==0.52.1'
@@ -40,7 +85,7 @@ variables:
 check-commit:
   extends:
     - .fdo.ci-fairy
-  stage: review
+  stage: "Merge request checks"
   script:
     - ci-fairy check-commits --signed-off-by --junit-xml=results.xml
   variables:
@@ -50,20 +95,24 @@ check-commit:
       junit: results.xml
 
 
+# Build our base container image, which contains the core distribution, the
+# toolchain, and all our build dependencies. This will be reused in the build
+# stage.
 debian:buster@container-prep:
   extends:
     - .debian.buster
     - .fdo.container-build@debian
-  stage: prep
+  stage: "Base container"
   variables:
     GIT_STRATEGY: none
 
 
+# Full build and test.
 build-native:
   extends:
     - .debian.buster
     - .fdo.distribution-image@debian
-  stage: build
+  stage: "Build and test"
   script:
   - export BUILD_ID="wayland-$CI_JOB_NAME_$CI_COMMIT_SHA-$CI_JOB_ID"
   - export PREFIX="$(pwd)/prefix-$BUILD_ID"