From 0bca8f0b2afa21b550d24ee77c148f549806f95a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20K=C4=99pie=C5=84?= <michal@isc.org>
Date: Tue, 4 Jan 2022 14:37:52 +0100
Subject: [PATCH] Add a tarball-based documentation-building job

The existing "docs" GitLab CI job operates on a Git repository rather
than a source tarball.  This prevents it from detecting issues caused by
files missing from source tarballs.  Add a new GitLab CI job similar to
the "docs" one, but using a source tarball rather than a Git repository.
Extract YAML bits used by multiple job definitions into anchors to avoid
code duplication.  Drop the "allow_failure: false" key in the process as
it is the implicit default for non-manual jobs.  Replace the
"artifacts:paths" key with "artifacts:untracked" in order to include all
untracked files in the artifact archive for each documentation-building
job; this allows tarball-based artifacts to be properly captured and
also facilitates troubleshooting failed jobs.
---
 .gitlab-ci.yml | 46 ++++++++++++++++++++++++++++++----------------
 1 file changed, 30 insertions(+), 16 deletions(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 70bca788c1..899dbabe08 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -257,6 +257,12 @@ stages:
         grep "^#define HAVE_READLINE_READLINE" config.h;
       fi
 
+# Unpack release tarball and continue work in the extracted directory.
+.unpack_release_tarball: &unpack_release_tarball
+  - tar --extract --file bind-*.tar.${TARBALL_EXTENSION}
+  - rm -f bind-*.tar.${TARBALL_EXTENSION}
+  - cd bind-*
+
 # Move the out-of-tree workspace to CI project dir to save it for use in
 # dependent jobs.
 .save_out_of_tree_workspace: &save_out_of_tree_workspace
@@ -384,6 +390,17 @@ stages:
       - tsan/
     when: on_failure
 
+.docs: &docs_job
+  stage: docs
+  script:
+    - *configure
+    - make -j${BUILD_PARALLEL_JOBS:-1} -k doc V=1
+    - qpdf --check doc/arm/_build/latex/Bv9ARM.pdf
+    - find doc/man/ -maxdepth 1 -name "*.[0-9]" -exec mandoc -T lint "{}" \; | ( ! grep -v -e "skipping paragraph macro. sp after" -e "unknown font, skipping request. ft C" )
+  artifacts:
+    untracked: true
+    expire_in: "1 month"
+
 ### Job Definitions
 
 # Jobs in the precheck stage
@@ -502,24 +519,23 @@ tarball-create:
 docs:
   <<: *release_branch_triggering_rules
   <<: *base_image
-  stage: docs
+  <<: *docs_job
   before_script:
     - test -w "${CCACHE_DIR}" && export PATH="/usr/lib/ccache:${PATH}"
-  script:
-    - *configure
-    - make -j${BUILD_PARALLEL_JOBS:-1} -k doc V=1
-    - qpdf --check doc/arm/_build/latex/Bv9ARM.pdf
-    - find doc/man/ -maxdepth 1 -name "*.[0-9]" -exec mandoc -T lint "{}" \; | ( ! grep -v -e "skipping paragraph macro. sp after" -e "unknown font, skipping request. ft C" )
   needs:
     - job: autoreconf
       artifacts: true
-  allow_failure: false
-  artifacts:
-    paths:
-      - doc/arm/
-      - doc/man/
-      - doc/misc/
-    expire_in: "1 month"
+
+docs:tarball:
+  <<: *schedules_tags_web_triggering_rules
+  <<: *base_image
+  <<: *docs_job
+  before_script:
+    - test -w "${CCACHE_DIR}" && export PATH="/usr/lib/ccache:${PATH}"
+    - *unpack_release_tarball
+  needs:
+    - job: tarball-create
+      artifacts: true
 
 push:docs:
   <<: *base_image
@@ -808,9 +824,7 @@ gcc:tarball:
   <<: *base_image
   <<: *build_job
   before_script:
-    - tar --extract --file bind-*.tar.${TARBALL_EXTENSION}
-    - rm -f bind-*.tar.${TARBALL_EXTENSION}
-    - cd bind-*
+    - *unpack_release_tarball
   needs:
     - job: tarball-create
       artifacts: true