Track upstream release series for generated references and add rebuild triggers - #468
Open
miharp wants to merge 2 commits into
Open
Track upstream release series for generated references and add rebuild triggers#468miharp wants to merge 2 commits into
miharp wants to merge 2 commits into
Conversation
Since the version pin table (153aec6), each generated product's reference pages build from an exact tag in _data/products.yml, so every point release needs a manual docs bump. The 8.x man pages are still on 8.28.0 and the OpenFact pin on 5.6.1 while 8.28.1 and 5.7.0 have been out for weeks. The exact pin exists to keep a collection from jumping majors: "newest stable" is repo-global, so once 9.0.0 ships an unpinned 8.x collection would build from 9.x. A series-bounded newest-stable keeps that property without the toil, so `ref:` now accepts either form: - a series such as "8.x" (or "9.0.x"), resolved at build time to the newest non-prerelease tag whose leading segments match. Prereleases never match, and a series with no stable tag raises rather than silently building nothing. - an exact tag, built verbatim, for prereleases and frozen older majors. Resolution happens in the per-product build (resolve_version), where the vendored clone's tags are already available, so references:all passes the ref through unchanged and VERSION=8.x works for local runs too. The current stable rows (openvox 8x, openfact 5x, openbolt 5x) switch to series refs; the 9.x prerelease keeps its exact pin. MAINTAINING.md's cutover runbook is updated so Phase 1 leaves 8.x tracking and Phase 2 freezes it at GA. Part of OpenVoxProject#467. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>
Add repository_dispatch (event type upstream-release) and workflow_dispatch triggers to the autopublish workflow. With products.yml refs tracking release series, the only thing standing between an upstream tag and updated reference pages is a build, and until now only a docs merge could start one. An upstream release workflow can now send a dispatch after tagging, and maintainers get a manual "rebuild and publish now" button for cases like an upstream doc-string fix or a release-table refresh that fell back to committed data. workflow_dispatch can be started from any branch or tag, and github.sha follows that ref, so the test job is guarded to master; skipping it skips build and deploy too. push is already limited to master and repository_dispatch always runs on the default branch. Dispatched runs show what triggered them via run-name (e.g. "Rebuild for openvox 8.28.1") when the sender includes product and version in the payload; without a payload the name is empty so GitHub falls back to the default. Since dispatches and merges can now overlap, and every run deploys master's head, add a concurrency group that queues rather than cancels, so a build is never killed mid-deploy. Part of OpenVoxProject#467. Co-authored-by: Claude <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>
miharp
force-pushed
the
docs/track-series-ref
branch
from
August 29, 2026 14:35
be9c98a to
91ac6b1
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #467.
Problem
Generated reference pages build from an exact upstream tag pinned in
_data/products.yml, so every point release needs a manual bump. That has not been happening: production still generates the 8.x man pages from 8.28.0 (8.28.1 shipped 2026-07-07) and the OpenFact references from 5.6.1 (5.7.0 is out). Separately, the site only rebuilds on a docs merge, so nothing refreshes it when upstream releases.Changes
ref:can track a release series._data/products.ymlnow accepts either form:Resolution happens in the per-product build (
PuppetReferences.resolve_version,Repo#newest_release(series:)), where the vendored clone's tags are already available, soreferences:allpasses the value through andVERSION=8.xworks for local runs too. A series never resolves to a prerelease, and a series with no stable tag raises rather than silently building nothing. The bound is what keeps this safe: an unbounded "newest stable" is repo-global and would jump majors once 9.0.0 ships.The current-stable rows (
openvox8x,openfact5x,openbolt5x) switch to series refs. The 9.x row keeps its exact prerelease pin. Theproducts.ymlheader and the MAINTAINING.md cutover runbook are updated: Phase 1 leaves 8.x tracking, Phase 2 switches 9.x to"9.x"and freezes 8.x at its final tag.Upstream releases can trigger a rebuild.
autopublish.yamlgainsrepository_dispatch(typeupstream-release) andworkflow_dispatchtriggers, arun-nameso dispatched runs show what triggered them, and a queue-only concurrency group since dispatches and merges can now overlap. The sending side (an optional step inshared-actions/release.ymlplus token scope) is tracked in #467 and is not part of this PR; merging this alone already rebuilds from the new refs, since_data/products.ymlmatches the push path filter.Verification
Full generation runs from this branch, all exit 0:
VERSIONreferences:openvox8.xreferences:openfact5.xreferences:openbolt5.xResolver checks against the vendored clones:
9.xraises (no stable tag),9.0.0-beta2and8.28.0pass through verbatim.rake rubocop,actionlint, and markdownlint are clean.The NOTE line on the
puppet agentman page, production vs. this branch built locally:The production date is the point: the site was rebuilt seven weeks after 8.28.1 shipped and still used the pinned tag. The local build's log shows the series resolving:
Using tag 8.28.1 -> _openvox_8x.Trade-off
Rebuilding an old docs commit no longer guarantees the same reference pages for the current stable series, because the series ref resolves against whatever tags exist at build time. Frozen majors and prereleases keep exact pins, so they are unaffected. The build log prints the resolved tag and every generated page's NOTE line records it, so what any given build used is always recoverable.
Assisted by Claude.