Clean up CI docs a bit

.gitlab-ci.yml

@@ -9,9 +9,25 @@
 # To accomplish this we use the ci executable in ./ci. This drives a set of
 # cabal v2-build builds and preserves their results.
 #
-# The compiler to be tested can be taken from a number of sources. The
-# build-master and build-9-* jobs form the validation pipeline of the
-# head.hackage repository. In addition, other GitLab projects (e.g. ghc/ghc>)
+# The execution flow looks something like:
+#
+# - Gitlab runner
+#   - (nix run)
+#     - run-ci
+#       - ./run-ci (the Nix package just wraps the script)
+#         - (nix run) (when USE_NIX=1)
+#           - head-hackage-ci $EXTRA_OPTS (a Cabal project in ci/)
+#             - ci/Main.hs
+#               - TestPatches.testPatches <$> TestPatches.config
+#                 - option '--test-package'
+#               - <something similar for building the packages>
+#
+# EXTRA_OPTS are injected into the execution flow inside ./run-ci, which in turn
+# sources them from ci/config.sh.
+#
+# The compiler to be tested can be taken from a number of sources.
+# head.hackage's own validation pipeline runs against GHC HEAD and the three
+# supported major versions. In addition, other GitLab projects (e.g. ghc/ghc>)
 # can trigger a multi-project pipeline, specifying a GHC binary distribution
 # via either the GHC_TARBALL or UPSTREAM_* variables.
 #
@@ -39,7 +55,7 @@ variables:
 
   # Multi-project pipeline variables:
   #
-  # These are set by the "upstream" pipeline for `build-pipeline` pipelines:
+  # These are set by the "upstream" pipeline for downstream pipelines:
   #
   #   UPSTREAM_PROJECT_PATH: The path of the upstream project (e.g. `ghc/ghc`)
   #   UPSTREAM_PIPELINE_ID: The ID of the upstream pipeline
@@ -49,7 +65,7 @@ variables:
   #   UPSTREAM_COMMIT_SHA: The ref or commit SHA of the GHC build to be tested
   #
 
-  # We explictly set the locale to avoid happy chocking up on UTF-8 source code. See #31
+  # We explictly set the locale to avoid happy choking up on UTF-8 source code. See #31
   LANG: "C.UTF-8"
 
 stages: