Skip to content

docs(release): add a reusable release playbook, retire the root RELEASE.md - #644

Merged
brickbots merged 2 commits into
mainfrom
docs/release-playbook
Nov 19, 2026
Merged

brickbots merged 2 commits into
mainfrom
docs/release-playbook

Conversation

@brickbots

@brickbots brickbots commented Sep 6, 2026 •

Copy link
Copy Markdown
Owner

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 release branch when NixOS becomes the product. It removes the old RELEASE.md at 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:

  • Phases 1 to 8 for a 2.x release. From the version number to the work after the update is offered. The steps come from the 2.6.1, 2.6.2 and 2.6.3 plans, and from pifinder_update.sh, pifinder_post_update.sh and ui/software.py.
  • The rule for documentation fixes between releases. The published manual is built from release. A fix on main reaches readers only after main is merged into release. This is safe only if the two branches were the same before the fix.
  • A pointer to the NixOS release process. That process is in nixos/RELEASE.md on the nixos branch of mrosseel/PiFinder. This document does not repeat it.
  • The migration, where the two lines meet. 2.6.4 is the first Pi OS release that can move a unit to NixOS. The section lists what cannot change after 2.6.4 ships, and the checks before the migration gate opens.
  • A plan for the release branch. 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.

Item First version Now
Check for merge conflicts 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 section Repeated the mechanics. Four statements were wrong: the gate flag, the cache address, the reason for the size limit of the migration file, and who makes the tag. A short pointer to nixos/RELEASE.md.
Check of .github/ "Must be the same on release and main." This cannot be true before a release. Says which copy of a workflow runs. release is the default branch, and its old release.yml writes the manifest key that 2.6.3 reads. Until the 2.6.4 release, start that workflow with --ref main.
Decision record numbers "No gaps." Gaps are correct: 0036 to 0045 are on the NixOS line.
Manual per release "Nothing exists for 2.2 to 2.6." /en/v2.6.3/ exists. The "previous versions" notes do not list it yet.

Decisions for 2.6.4

Plan for the release branch

This is a proposal. Nothing is done yet.

release has four functions today. Only the first one needs the name release.

Function Plan When
Pi OS units get their code, version.txt and migration_gate.json from it No change. The name is in the update script of every unit. Never
Default branch on GitHub main becomes the default branch. After the 2.6.4 release
main is merged into it for a release Only small fixes go to release, each as a pull request to release. When #379 merges
The manual at /en/release/ is built from it /en/release/ redirects to /en/stable/. The Pi OS manual stays at /en/v2.6.x/. First stable 3.x release

@mrosseel, two points need your opinion:

  1. The plan says: do not merge NixOS support #379 before Pi OS can continue with small fixes only. After NixOS support #379, main cannot be released to Pi OS units, because python/requirements.txt and migration_gate.json are not on the nixos branch.
  2. nixos/RELEASE.md has four old statements. They are in the list "One-time tasks" of the document.

Not complete

  • Phase 6: how the 2.x card image is made and how it gets to the download server. Nothing in the repository describes this.
  • Phase 7: the Discord channel, the Cloudy Nights thread, and the email list of the owners.
  • With an open gate, the Software screen offers the migration before it reads version.txt. This statement comes from the code. It is not yet tested on a unit.

🤖 Generated with Claude Code

brickbots and others added 2 commits September 6, 2026 14:53
…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>
@brickbots
brickbots merged commit 3be7df7 into main Nov 19, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant