Patch Antora playbook for testing feature branches

add-test-branches-to-playbook.sh

#!/usr/bin/env bash

set -euo pipefail

# # INPUT
# The playbook (YAML file) you want to patch"
playbook="${1}"
# URL of the Git repository that contains the content source under test;
# typically, this will be the HTTPS clone URL of that repository:
repo_under_test="${2}"
# The name of the Git branch the content of which is under test:
# (TIP: on Jenkins, $GIT_BRANCH is probably what you want.)
branch_under_test="${3}"
# The directory that contains the content source under test,
# relative to the repository root:
start_path_under_test="${4}"

# # OUTPUT
# Prints an Antora playbook to stdout that is the same as the input playbook, except
#
# - the given branch is removed from the 'branches' list of the content source with the given URL,
#   if it is present there.
# - the given branch is added to the 'branches' list of all _other_ content sources,
#   unless it's a default or Renovate branch.
# - finally, a local content source for the currently checked out respository is added.
#
# See test/add-test-branches-to-playbook for an example.

default_branches=(main master develop)
renovate_branches_pattern="^renovate/"

# editorconfig-checker-disable
# (0) Remove current branch from this content source; version would conflict with local checkout (2)!
remove_this=".content.sources[] |= (select(.url == \"${repo_under_test}\" and .start_path == \"${start_path_under_test}\") | .branches |= filter(. != \"${branch_under_test}\"))"
# (1) Add matching branch to all _other_ content sources, _if_ it's a feature branch
#     credits: https://stackoverflow.com/a/15901346/539599 (NB: it's a substring match, which is okay here)
branch_pattern="\b${branch_under_test}\b"
if [[ ! ${default_branches[*]} =~ ${branch_pattern} ]] \
  && [[ ! ${branch_under_test} =~ ${renovate_branches_pattern} ]];
then
  add_others=".content.sources[] |= (select(.url != \"${repo_under_test}\") | .branches += \"${branch_under_test}\")"
else
  add_others="." # that's a NOP for yq
fi
# (2) Add local checkout as content source
add_local=".content.sources += { \"url\": \"~+\", \"start_path\": \"${start_path_under_test}\", \"branches\": [\"HEAD\"]}"
# editorconfig-checker-enable

# shellcheck disable=SC2002
  cat "${playbook}" \
| yq "${remove_this}" \
| yq "${add_others}" \
| yq "${add_local}" \
| yq --prettyPrint # normalize for robust testing

example.sh

#!/usr/bin/env sh

add-test-branches-to-playbook \
    "given-playbook.yaml" \
    "some-repo" "feat/stuff-to-test" "some-path" \
    > "actual-playbook.yaml"
    
diff -B \
    "expected-playbook.yaml" \
    "actual-playbook.yaml"

expected-playbook.yaml

---
site:
  start_page: home::index.adoc
  title: Documentation Test
content:
  sources:
    - url: landing-page
      start_path: /
      branches:
        - main
        - feat/stuff-to-test
    - url: some-repo
      start_path: some-path
      branches:
        - docs/v1.0.0
    - url: other-repo
      start_path: other-path
      branches:
        - develop
        - feat/stuff-to-test
    - url: ~+
      start_path: some-path
      branches:
        - HEAD
ui:
  bundle:
    url: test/minimal-ui-bundle.zip
    start_path: ""
  output_dir: ui
urls:
  html_extension_style: default
  redirect_facility: static
  latest_version_segment: latest

given-playbook.yaml

---
site:
  start_page: "home::index.adoc"
  title: "Documentation Test"
content:
  sources:
    - url: "landing-page"
      start_path: "/"
      branches:
        - "main"
    - url: "some-repo"
      start_path: "some-path"
      branches:
        - "docs/v1.0.0"
        - "feat/stuff-to-test"
    - url: "other-repo"
      start_path: "other-path"
      branches:
        - "develop"
ui:
  bundle:
    url: "test/minimal-ui-bundle.zip"
    start_path: ""
  output_dir: "ui"
urls:
  html_extension_style: "default"
  redirect_facility: "static"
  latest_version_segment: "latest"

Ever faced the problem of testing an Antora content source that links to other content sources?

• log-failure-level==fatal lets you get away with bad xrefs inside your own sources, while
• log-failure-level==error fails your build unless you include all other content sources (that you link to, at least), but
• the production playbook does not reference the changes you want to test!

This scripts helps in that it patches the production playbook to have that reference, and adds a branch to all content sources (so you can test interdependent changes in multiple content sources together).

With the patched playbook, log-failure-level==error (or even warn) does not produce "false" errors!