From 912372a74c68af1d72be174e4df6edf3351f6f79 Mon Sep 17 00:00:00 2001 From: Houston Putman Date: Tue, 9 Jun 2026 12:44:54 -0700 Subject: [PATCH] Generate antora.yml for local builds; keep committed file release-managed Follow up from https://github.com/apache/solr-operator/pull/834 The committed docs/antora.yml is what the published Reference Guide uses for a branch, so it must reflect that branch's released version (not a prerelease) and should only change at release time. Previously `make docs` and propagate_version.sh regenerated it from version/version.go on every run, leaving release branches showing a prerelease version. Mirror Solr's approach: - `make docs`/`check-docs` now stage a build dir (docs/build/staging) with a throwaway antora.yml generated from version/version.go, so local previews show the in-development version without touching the committed file. - generate_antora_yaml.sh takes -o (output) for staging. - Remove antora.yml regeneration from propagate_version.sh; the release wizard regenerates the committed docs/antora.yml at release (after the prerelease suffix is stripped), so it reflects the released version. Co-Authored-By: Claude Opus 4.8 (1M context) --- Makefile | 20 +++++++++++-- docs/local-playbook.yml | 2 +- hack/docs/generate_antora_yaml.sh | 35 ++++++++++++++++------- hack/release/version/propagate_version.sh | 5 ---- hack/release/wizard/releaseWizard.yaml | 14 ++++++++- 5 files changed, 56 insertions(+), 20 deletions(-) diff --git a/Makefile b/Makefile index 3b903acb..186f818c 100644 --- a/Makefile +++ b/Makefile @@ -344,13 +344,27 @@ helm-deploy-operator: helm-dependency-build docker-build ## Deploy the current v # for local previewing only; the official site is published as an additional # component of the Reference Guide from the apache/solr repo. ANTORA_IMAGE ?= antora/antora:3.1.12 +DOCS_STAGING = docs/build/staging .PHONY: generate-antora-yaml -generate-antora-yaml: ## Generate docs/antora.yml from version/version.go +# Writes the COMMITTED docs/antora.yml. This descriptor drives the published +# site for this branch, so it is only run at release time (by the release +# wizard) to reflect the released version -- NOT on every local build. +generate-antora-yaml: ## Regenerate the committed docs/antora.yml (release use) ./hack/docs/generate_antora_yaml.sh +.PHONY: docs-staging +# Stages a build dir with the modules and a throwaway antora.yml generated from +# version/version.go, so local previews show the in-development version without +# modifying the committed docs/antora.yml. +docs-staging: + rm -rf $(DOCS_STAGING) + mkdir -p $(DOCS_STAGING) + cp -r docs/modules $(DOCS_STAGING)/modules + ./hack/docs/generate_antora_yaml.sh -o $(DOCS_STAGING)/antora.yml + .PHONY: docs -docs: generate-antora-yaml ## Build the operator Antora docs site locally for previewing (requires Docker) +docs: docs-staging ## Build the operator Antora docs site locally for previewing (requires Docker) docker run --rm -v "$(PROJECT_DIR):/antora" -w /antora/docs $(ANTORA_IMAGE) --fetch --to-dir build/site local-playbook.yml @echo "Docs built. Open docs/build/site/index.html in a browser to preview." @@ -359,7 +373,7 @@ docs-clean: ## Remove the locally-generated documentation site rm -rf docs/build .PHONY: check-docs -check-docs: generate-antora-yaml ## Validate the operator docs build with no broken references (requires Docker) +check-docs: docs-staging ## Validate the operator docs build with no broken references (requires Docker) docker run --rm -v "$(PROJECT_DIR):/antora" -w /antora/docs $(ANTORA_IMAGE) --fetch --log-failure-level=warn --to-dir build/site local-playbook.yml ##@ Dependencies diff --git a/docs/local-playbook.yml b/docs/local-playbook.yml index cc07b7de..45c364b5 100644 --- a/docs/local-playbook.yml +++ b/docs/local-playbook.yml @@ -37,7 +37,7 @@ content: - url: .. # HEAD builds the current worktree, including uncommitted changes. branches: HEAD - start_path: docs + start_path: docs/build/staging # No "edit this page" links in local preview. edit_url: false diff --git a/hack/docs/generate_antora_yaml.sh b/hack/docs/generate_antora_yaml.sh index 8cc1b3da..c4d62cd7 100755 --- a/hack/docs/generate_antora_yaml.sh +++ b/hack/docs/generate_antora_yaml.sh @@ -14,29 +14,43 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Generates docs/antora.yml from docs/antora.template.yml, deriving the Antora -# component version from version/version.go. This keeps the Antora version in -# lock-step with the operator version without requiring Gradle (unlike Solr). +# Generates an Antora component descriptor (antora.yml) for the operator docs +# from docs/antora.template.yml, deriving the version from version/version.go. # -# v0.10.0 (suffix "") -> version '0_10', display_version '0.10' -# v0.10.0 (suffix "prerelease") -> version '0_10', display_version '0.10-prerelease', prerelease: -prerelease +# By default it writes the COMMITTED docs/antora.yml -- the descriptor the +# published Reference Guide uses for this branch. The release wizard regenerates +# it (via `make generate-antora-yaml`) at the steps where the published version +# changes; it is deliberately NOT regenerated on the post-release patch bump, so +# a release branch stays pinned to its last released version. Local preview +# builds (`make docs`) pass -o to write a throwaway descriptor into the +# build/staging directory, so the committed file is never modified during a +# normal build. +# +# Usage: generate_antora_yaml.sh [-o OUTPUT] +# -o OUTPUT output file (default: docs/antora.yml) +# +# version.go v0.9.1 -> version '0_9', display_version 'v0.9' +# version.go v0.10.0 (prerelease) -> version '0_10', display_version 'v0.10-prerelease', prerelease: -prerelease set -eu set -o pipefail -# Resolve the project root (this script lives in hack/docs/). SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" PROJECT_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)" - -VERSION_GO="${PROJECT_DIR}/version/version.go" TEMPLATE="${PROJECT_DIR}/docs/antora.template.yml" OUTPUT="${PROJECT_DIR}/docs/antora.yml" -# Parse Version (e.g. v0.10.0) and VersionSuffix (e.g. prerelease) from version.go. +while getopts ":o:" opt; do + case "${opt}" in + o) OUTPUT="${OPTARG}" ;; + *) echo "Usage: $0 [-o OUTPUT]" >&2; exit 2 ;; + esac +done + +VERSION_GO="${PROJECT_DIR}/version/version.go" RAW_VERSION="$(grep -E 'Version([[:space:]]+)=' "${VERSION_GO}" | head -1 | sed -E 's/.*["'"'"']([^"'"'"']*)["'"'"'].*/\1/')" SUFFIX="$(grep -E 'VersionSuffix([[:space:]]+)=' "${VERSION_GO}" | sed -E 's/.*["'"'"']([^"'"'"']*)["'"'"'].*/\1/')" -# Strip leading 'v' and split into semver parts. SEMVER="${RAW_VERSION#v}" IFS='.' read -r MAJOR MINOR PATCH <<< "${SEMVER}" @@ -51,6 +65,7 @@ else PRERELEASE_LINE="" fi +mkdir -p "$(dirname "${OUTPUT}")" # Substitute tokens. Use '|' as the sed delimiter; values contain no '|'. sed \ -e "s|@ANTORA_VERSION@|${ANTORA_VERSION}|g" \ diff --git a/hack/release/version/propagate_version.sh b/hack/release/version/propagate_version.sh index c1dbe37e..ae87aba3 100755 --- a/hack/release/version/propagate_version.sh +++ b/hack/release/version/propagate_version.sh @@ -98,9 +98,4 @@ fi } > helm/solr/README.md.tmp && mv helm/solr/README.md.tmp helm/solr/README.md -# Regenerate the operator Antora component descriptor (docs/antora.yml) from -# version/version.go. Docs pages reference the version via the {operator-version} -# attribute defined there, so no per-page version edits are needed. -./hack/docs/generate_antora_yaml.sh - make manifests diff --git a/hack/release/wizard/releaseWizard.yaml b/hack/release/wizard/releaseWizard.yaml index e4cc97e9..58f5b7b5 100644 --- a/hack/release/wizard/releaseWizard.yaml +++ b/hack/release/wizard/releaseWizard.yaml @@ -458,6 +458,10 @@ groups: - !Command cmd: make propagate-version tee: true + - !Command + cmd: make generate-antora-yaml + comment: Regenerate the committed docs/antora.yml for the new version. + tee: true - !Command comment: Make sure the edits done by propagating the version are ok, then push cmd: git add -u . && git commit -m "Add next major version {{ next_version }}" && git push @@ -490,6 +494,10 @@ groups: - !Command cmd: make propagate-version tee: true + - !Command + cmd: make generate-antora-yaml + comment: Regenerate the committed docs/antora.yml for the new version. + tee: true - !Command comment: Make sure the edits done by propagating the version are ok, then push cmd: git add -u . && git commit -m "Add next minor version {{ next_version }}" && git push @@ -755,10 +763,14 @@ groups: comment: Remove the prerelase suffix from the version. stdout: true - !Command - cmd: ./hack/release/version/propagate_version.sh + cmd: make propagate-version comment: Propagate the new version throughout the repo. logfile: propagate_version.log tee: true + - !Command + cmd: make generate-antora-yaml + comment: Regenerate the committed docs/antora.yml to the released version. + tee: true - !Command cmd: ./hack/release/artifacts/set_signing_key.sh -f "{{ gpg_fingerprint | default('', True) }}" comment: Set the signing key throughout the repo.