Add comments

.gitlab-ci.yml

@@ -1,6 +1,9 @@
 variables:
+  # Not normally needed, but may be if some script uses `apt-get install`.
   DEBIAN_FRONTEND: noninteractive
+  # Locale settings do not affect the build, but might affect tests.
   LC_ALL: C
+
   CI_REGISTRY_IMAGE: registry.gitlab.isc.org/isc-projects/images/bind9
   CCACHE_DIR: "/ccache"
   SOFTHSM2_CONF: "/var/tmp/softhsm2/softhsm2.conf"
@@ -11,6 +14,8 @@ stages:
   - test
   - push
 
+### Runner Tag Templates
+
 .linux-amd64: &linux_amd64
   tags:
     - linux
@@ -21,6 +26,10 @@ stages:
     - linux
     - i386
 
+### Docker Image Templates
+
+# CentOS
+
 .centos-centos6-amd64: &centos_centos6_amd64_image
   image: "$CI_REGISTRY_IMAGE:centos-centos6-amd64"
   <<: *linux_amd64
@@ -29,6 +38,8 @@ stages:
   image: "$CI_REGISTRY_IMAGE:centos-centos7-amd64"
   <<: *linux_amd64
 
+# Debian
+
 .debian-jessie-amd64: &debian_jessie_amd64_image
   image: "$CI_REGISTRY_IMAGE:debian-jessie-amd64"
   <<: *linux_amd64
@@ -53,6 +64,8 @@ stages:
   image: "$CI_REGISTRY_IMAGE:debian-sid-i386"
   <<: *linux_i386
 
+# Ubuntu
+
 .ubuntu-xenial-amd64: &ubuntu_xenial_amd64_image
   image: "$CI_REGISTRY_IMAGE:ubuntu-xenial-amd64"
   <<: *linux_amd64
@@ -69,6 +82,8 @@ stages:
   image: "$CI_REGISTRY_IMAGE:ubuntu-bionic-i386"
   <<: *linux_i386
 
+### Job Templates
+
 .default-triggering-rules: &default_triggering_rules
   only:
     - merge_requests
@@ -125,6 +140,10 @@ stages:
     expire_in: "1 week"
     when: on_failure
 
+### Job Definitions
+
+# Jobs in the precheck stage
+
 misc:sid:amd64:
   <<: *precheck_job
   script:
@@ -151,6 +170,8 @@ misc:sid:amd64:
   <<: *precheck_job
   script: util/check-cocci
 
+# Jobs for doc builds on Debian Sid (amd64)
+
 docs:sid:amd64:
   <<: *debian_sid_amd64_image
   stage: build
@@ -179,6 +200,8 @@ push:docs:sid:amd64:
     - master@isc-projects/bind9
     - /^v9_[1-9][0-9]$/@isc-projects/bind9
 
+# Jobs for regular GCC builds on CentOS 6 (amd64)
+
 gcc:centos6:amd64:
   variables:
     CC: gcc
@@ -199,6 +222,8 @@ unit:gcc:centos6:amd64:
   dependencies:
     - gcc:centos6:amd64
 
+# Jobs for regular GCC builds on CentOS 7 (amd64)
+
 gcc:centos7:amd64:
   variables:
     CC: gcc
@@ -219,6 +244,8 @@ unit:gcc:centos7:amd64:
   dependencies:
     - gcc:centos7:amd64
 
+# Jobs for regular GCC builds on Debian 8 Jessie (amd64)
+
 gcc:jessie:amd64:
   variables:
     CC: gcc
@@ -239,6 +266,8 @@ unit:gcc:jessie:amd64:
   dependencies:
     - gcc:jessie:amd64
 
+# Jobs for regular GCC builds on Debian 9 Stretch (amd64)
+
 gcc:stretch:amd64:
   variables:
     CC: gcc
@@ -258,6 +287,8 @@ unit:gcc:stretch:amd64:
   dependencies:
     - gcc:stretch:amd64
 
+# Jobs for regular GCC builds on Debian Sid (amd64)
+
 gcc:sid:amd64:
   variables:
     CC: gcc
@@ -287,6 +318,8 @@ unit:gcc:sid:amd64:
   dependencies:
     - gcc:sid:amd64
 
+# Jobs for regular GCC builds on Debian Sid (i386)
+
 gcc:sid:i386:
   variables:
     CC: gcc
@@ -307,6 +340,8 @@ unit:gcc:sid:i386:
   dependencies:
     - gcc:sid:i386
 
+# Jobs for regular GCC builds on Ubuntu 16.04 Xenial Xerus (amd64)
+
 gcc:xenial:amd64:
   variables:
     CC: gcc
@@ -326,6 +361,8 @@ unit:gcc:xenial:amd64:
   dependencies:
     - gcc:xenial:amd64
 
+# Jobs for regular GCC builds on Ubuntu 18.04 Bionic Beaver (amd64)
+
 gcc:bionic:amd64:
   variables:
     CC: gcc
@@ -346,6 +383,8 @@ unit:gcc:bionic:amd64:
   dependencies:
     - gcc:bionic:amd64
 
+# Jobs for GCC builds with ASAN enabled on Debian Sid (amd64)
+
 asan:sid:amd64:
   variables:
     CC: gcc
@@ -367,6 +406,8 @@ unit:asan:sid:amd64:
   dependencies:
     - asan:sid:amd64
 
+# Jobs for Clang builds on Debian Stretch (amd64)
+
 clang:stretch:amd64:
   variables:
     CC: clang
@@ -381,6 +422,8 @@ unit:clang:stretch:amd64:
   dependencies:
     - clang:stretch:amd64
 
+# Jobs for Clang builds on Debian Stretch (i386)
+
 clang:stretch:i386:
   variables:
     CC: clang
@@ -389,6 +432,8 @@ clang:stretch:i386:
   <<: *debian_stretch_i386_image
   <<: *build_job
 
+# Jobs for PKCS#11-enabled GCC builds on Debian Sid (amd64)
+
 pkcs11:sid:amd64:
   variables:
     CC: gcc
@@ -409,6 +454,8 @@ unit:pkcs11:sid:amd64:
   dependencies:
     - pkcs11:sid:amd64
 
+# Jobs for GCC builds with assertions compiled away on Debian Sid (amd64)
+
 noassert:sid:amd64:
   variables:
     CC: gcc