Repository navigation
docs(release): add a reusable release playbook, retire the root RELEASE.md - #644
Merged
Merged
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
…nd the release-branch plan The playbook was written on 2026-09-05. Since then #657 and #658 landed, and parts of it became wrong. One command was wrong from the start. The conflict check piped `git merge-tree` into `grep -c '<<<<<<<'`. The two-argument form prints a tree id and a file list, never conflict markers, so the count is always 0. It is 0 on the 2.6.3 cut, which had a version.txt conflict. The check now uses `--write-tree` and the exit code, and compares the result with main's tree. The NixOS section repeated mechanics that belong to nixos/RELEASE.md on the nixos branch, and four statements no longer matched the code: the gate flag (now nixos_migration), the cache host, the reason for the tarball size limit, and who creates the tag. The section is now a pointer. Two checks could not pass: ".github byte-identical" (the difference is part of the cut) and "ADR ledger has no gaps" (0036 to 0045 are on the NixOS line). The first now names the real hazard: release is the default branch, and its old release.yml writes the manifest key that 2.6.3 reads. New sections: - Between cuts: the rule for promoting docs from main to release, and the fact that a promotion also carries code (#639 and #640 reached release after the v2.6.3 tag with no version bump). - Where the tracks meet: 2.6.4 is the first Pi OS release that can migrate to NixOS. The contract that freezes at the cut, the 7x SQUARE path that ignores the gate, the 90-day life of a beta, and opening the gate as a release of its own. - Decided for 2.6.4: #697 ships in it, and no stable NixOS release comes first. - A transition plan for the release branch: it stays the Pi OS line for ever, the default branch moves to main after the 2.6.4 cut, the cut from main ends when #379 merges, and /en/release/ redirects to /en/stable/ at the first stable 3.x. Docs snapshots: /en/v2.6.3/ exists, so the text no longer says nothing exists for 2.6. The "previous versions" notes were not updated for it; that step now belongs to the prep PR of the next release. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
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.
This pull request adds one document: the steps we follow to make a release. The last three releases each found the same problems again, because the steps were only in the plans of each release. The document also says how the Pi OS line and the NixOS line fit together, and what happens to the
releasebranch when NixOS becomes the product. It removes the oldRELEASE.mdat the top of the repository, which was a copy of the 2.6.1 notes.Only documents change. No code changes.
What the document contains
release_notes/RELEASE-PLAYBOOK.md:pifinder_update.sh,pifinder_post_update.shandui/software.py.release. A fix onmainreaches readers only aftermainis merged intorelease. This is safe only if the two branches were the same before the fix.nixos/RELEASE.mdon thenixosbranch ofmrosseel/PiFinder. This document does not repeat it.releasebranch. See below.Changes since the first version of this pull request
The first version was written on 2026-09-05. #657 and #658 merged after that date.
git merge-tree … | grep -c '<<<<<<<'. This always gives 0, also for the 2.6.3 release, which had a conflict.git merge-tree --write-tree, and its exit code.nixos/RELEASE.md..github/releaseandmain." This cannot be true before a release.releaseis the default branch, and its oldrelease.ymlwrites the manifest key that 2.6.3 reads. Until the 2.6.4 release, start that workflow with--ref main./en/v2.6.3/exists. The "previous versions" notes do not list it yet.Decisions for 2.6.4
Plan for the
releasebranchThis is a proposal. Nothing is done yet.
releasehas four functions today. Only the first one needs the namerelease.version.txtandmigration_gate.jsonfrom itmainbecomes the default branch.mainis merged into it for a releaserelease, each as a pull request torelease./en/release/is built from it/en/release/redirects to/en/stable/. The Pi OS manual stays at/en/v2.6.x/.@mrosseel, two points need your opinion:
maincannot be released to Pi OS units, becausepython/requirements.txtandmigration_gate.jsonare not on thenixosbranch.nixos/RELEASE.mdhas four old statements. They are in the list "One-time tasks" of the document.Not complete
version.txt. This statement comes from the code. It is not yet tested on a unit.🤖 Generated with Claude Code