Add comments

(cherry picked from commit a27b9dff18efa692162c6de550b6e4082ad024ed)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 17d547c1253996a3e0159bbd9c8189867a2860e2..d7ca95f619bccef5ab6e084a33624481012933a9 100644 (file)
--- a/.gitlab-ci.yml
+++ b/.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
@@ -124,6 +139,10 @@ stages:
     expire_in: "1 week"
     when: on_failure
 
+### Job Definitions
+
+# Jobs in the precheck stage
+
 misc:sid:amd64:
   <<: *precheck_job
   script:
@@ -150,6 +169,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
@@ -178,6 +199,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
@@ -198,6 +221,8 @@ unit:gcc:centos6:amd64:
   dependencies:
     - gcc:centos6:amd64
 
+# Jobs for regular GCC builds on CentOS 7 (amd64)
+
 gcc:centos7:amd64:
   variables:
     CC: gcc
@@ -218,6 +243,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
@@ -238,6 +265,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
@@ -257,6 +286,8 @@ unit:gcc:stretch:amd64:
   dependencies:
     - gcc:stretch:amd64
 
+# Jobs for regular GCC builds on Debian Sid (amd64)
+
 gcc:sid:amd64:
   variables:
     CC: gcc
@@ -286,6 +317,8 @@ unit:gcc:sid:amd64:
   dependencies:
     - gcc:sid:amd64
 
+# Jobs for regular GCC builds on Debian Sid (i386)
+
 gcc:sid:i386:
   variables:
     CC: gcc
@@ -306,6 +339,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
@@ -325,6 +360,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
@@ -345,6 +382,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
@@ -366,6 +405,8 @@ unit:asan:sid:amd64:
   dependencies:
     - asan:sid:amd64
 
+# Jobs for Clang builds on Debian Stretch (amd64)
+
 clang:stretch:amd64:
   variables:
     CC: clang
@@ -380,6 +421,8 @@ unit:clang:stretch:amd64:
   dependencies:
     - clang:stretch:amd64
 
+# Jobs for Clang builds on Debian Stretch (i386)
+
 clang:stretch:i386:
   variables:
     CC: clang
@@ -388,6 +431,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
@@ -408,6 +453,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