docs(release): add a reusable release playbook, retire the root RELEASE.md - #644
Open
brickbots wants to merge 1 commit into
Open
docs(release): add a reusable release playbook, retire the root RELEASE.md#644brickbots wants to merge 1 commit into
brickbots wants to merge 1 commit into
Conversation
…SE.md The 2.6.1, 2.6.2 and 2.6.3 cuts each rediscovered the same handful of things: an uncommitted version.txt bump that would have offered the update to nobody, stale ADR number reservations, new menu entries shifting menu indexes and breaking the keypress-counting web tests, a stale mypy cache reporting phantom errors. The per-release notes and test plans are the right place for what one release changed, but they are the wrong place for process, so it kept getting rebuilt from scratch. release_notes/RELEASE-PLAYBOOK.md is that process, distilled from those three cuts and from the actual mechanics in pifinder_update.sh, pifinder_post_update.sh, ui/software.py and release.yml. It separates the two tracks, which differ in who creates the tag: the 2.x line is entirely manual, while the 3.x NixOS workflow tags and publishes itself. New in it, and the reason this got written now: every release gets a docs build frozen at its own URL. Read the Docs still serves /en/v1.11.2/, /en/v2.0.4/ and /en/v2.1.1/, and index.rst, user_guide.rst and quick_start.rst all link to them, but nothing exists for 2.2 through 2.6. A user on 2.4 landing on /en/release/ today reads rev4 docs describing hardware and menus they do not have. The fix is one dashboard action per cut. We are not backfilling the gap, so those three notes need rewording to stop implying full coverage; that is tracked in the playbook. Tagging gets a rule for the same reason. v2.6.1 sits on a commit shared by both branches, but v2.6.3 landed on 31c900c, two commits past the release merge, because the tag went on afterwards. Since Read the Docs builds from the tag, a late tag now produces a docs snapshot of something that never shipped. RELEASE.md at the repo root was a byte-identical copy of release_notes/2.6.1.md, with version.txt reading 2.6.3 and nothing in the repo referencing it. Removed rather than refreshed: release_notes/X.Y.Z.md has been the real home since 2.6.1. Two sections are honest stubs. Nothing in this repo describes how the 2.x SD image is built or how it reaches CloudFront, and the Discord channel, Cloudy Nights thread and owner-email list still need filling in. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CYLTX561d4W4R8AHiM67j1
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.
Three cuts in a row (2.6.1, 2.6.2, 2.6.3) rediscovered the same handful of things.
release_notes/RELEASE-PLAYBOOK.mdis the process, pulled out of those plans so the next cut starts from it instead of from memory.What's in it
Phases 1 through 8, from picking the version number to what happens after the update is offered, plus the NixOS track as its own section. It's built from the three test plans and from the actual mechanics in
pifinder_update.sh,pifinder_post_update.sh,ui/software.pyand.github/workflows/release.yml.The two tracks are separated up front because they differ in who creates the tag. The 2.x line is entirely by hand: the merge, the tag, the GitHub release and the SD image. The NixOS workflow tags and publishes itself, so tagging first would collide.
Docs snapshots, the reason this got written now
Every release gets a docs build frozen at its own URL. Read the Docs still serves
/en/v1.11.2/,/en/v2.0.4/and/en/v2.1.1/, andindex.rst,user_guide.rstandquick_start.rstall link to them from the "previous versions" note. Nothing exists for 2.2 through 2.6. Someone on 2.4 hitting/en/release/today reads rev4 docs describing hardware and menus they don't have.The mechanism already exists (RTD builds a version per git tag, which is where
/en/v2.1.1/and/en/v3_hardware/came from), so this is one dashboard action per cut, not new infrastructure. We're not backfilling the gap. That leaves those three notes implying coverage they don't have, so rewording them is tracked in the playbook as a one-time task rather than done here.Tagging gets a rule
v2.6.1sits on a commit shared by both branches.v2.6.3landed on31c900c3, two commits past the release mergeefc75c2d, because the tag went on afterwards. Now that RTD builds from the tag, a late tag produces a docs snapshot of something that never shipped. The playbook says tag at the cut, on the commitreleasepointed at when the update opened.RELEASE.md
Removed. It was a byte-identical copy of
release_notes/2.6.1.md(125 lines, 24,529 bytes, same blob) whileversion.txtreads 2.6.3, andgit grepfinds nothing in the repo referencing it.release_notes/X.Y.Z.mdhas been the real home since 2.6.1, so refreshing it each cut would just be a second place to forget.Two honest stubs
Phase 6 (how the 2.x SD image is built and how it reaches CloudFront) is a TODO. Nothing in this repo describes it, so I'd rather it be visibly missing than quietly guessed. Phase 7 needs the Discord channel, the Cloudy Nights thread and where the owner-email list lives.
Docs only, no code touched.
🤖 Generated with Claude Code
https://claude.ai/code/session_01CYLTX561d4W4R8AHiM67j1