This is an automated email from the ASF dual-hosted git repository.
HoustonPutman pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr-operator.git
The following commit(s) were added to refs/heads/main by this push:
new ef3821b Generate antora.yml for local builds; keep committed file
release-managed (#835)
ef3821b is described below
commit ef3821baa73b19a90578688cbab28d6ef75f02a5
Author: Houston Putman <[email protected]>
AuthorDate: Tue Jun 9 13:56:57 2026 -0700
Generate antora.yml for local builds; keep committed file release-managed
(#835)
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) <[email protected]>
---
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 3b903ac..186f818 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 cc07b7d..45c364b 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 8cc1b3d..c4d62cd 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 c1dbe37..ae87aba 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 e4cc97e..58f5b7b 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('<gpg_fingerprint>', True) }}"
comment: Set the signing key throughout the repo.
