Add maintainer runbook for the major-version cutover#337
Draft
miharp wants to merge 1 commit into
Draft
Conversation
Document the copy-on-major-release cutover in a new MAINTAINING.md: how versions are wired (collections, the _latest symlink, products.yml, the three nav files, the version selector, generated references), and a two-phase procedure for adding a new major version — Phase 1 stands it up alongside as a preview, Phase 2 promotes it to latest and freezes the old one — plus rollback and the no-redirect caveat. The procedure was validated end to end with local OpenVox 9.x cutover dry runs of both phases, combined with the version selector. The content-string sweep uses `git grep` (so generated pages are excluded) over both the collection and the copied nav file, and the nav steps cover all three nav inputs: _data/nav/<key>.yml, _data/nav_map.yml, and _data/navigation.yml (the top bar). Part of OpenVoxProject#325. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>
4e1bf74 to
d7916dd
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
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.
What
Adds
MAINTAINING.md— a maintainer runbook for the major-version cutover, sothere's a concrete, shareable procedure for when OpenVox 9 (or any product's new
major) ships.
It covers:
_<product>_latestsymlink,_data/products.ymlas the registry, nav files, the version selector, and pinnedreference generation.
authored pages for version strings (
git grep, so generated pages are excluded),register the collection in
_config.yml, wire nav, add aproducts.ymlversionblock pinned to the new tag, generate + verify.
lateststays on the current major.latest(GA): repoint the symlink, move thelatestcollection's nav to the new version, set
latest:, freeze the old version's pin,and run the no-redirect page-set diff.
Validation
Validated end to end in a throwaway sandbox combined with the version selector
(#335) — a full OpenVox 9.x cutover of both phases, built against the pinned
9.0.0-alpha1references.Phase 1 — stand up 9.x alongside (preview)
Phase 2 — promote 9.x to latest (GA)
Result:
/openvox/latest/serves OpenVox 9, the version picker badges 9.x aslatest, and 8.x stays frozen. The version-string sweep leaves only legitimate
version-specific 8.x content (the release-notes history and hiera backward-compat
notes).
Part of #325.