Releases playbook
This playbook decides how work is merged and released. Sources: the org AGENTS.md and CONTRIBUTING.md as proposed in nyuchi/nyuchi-docs#118 (not merged when this was written), the repositories’ own workflow files, and owner messages as dated below. Reviewed 2026-11-17; the red-or-orange rule and follow-through added the same day. “Decided, not built” is said wherever that is the case, and where two sources disagree the conflict is listed under Open for the owner, not settled here.
The decisions
Section titled “The decisions”- The branch decides the bump (owner, 2026-10-04,
nyuchi/.github#80). A merge intostagingis the next patch. A release fromstagingto the default branch is the next minor. A major is made by hand only, with thesemver:majorlabel orbump: major; agents never release a major. Minor and patch have no cap and versions compare as numbers. A repository whose version lives in a file sets it to the next allowed version, and CI refuses anything else. - Feature and fix PRs go into
staging;stagingto the default branch is a release (the same rule). Open a draft PR first, with Conventional Commits titles. - The release PR is the app’s job, not the author’s.
bundu-release[bot](the enterprise-ownedbundu-releaseGitHub App, whose key lives only in theorg-releaseenvironment) opens thestagingto default-branch PR and turns auto-merge on, fromauto-release.yml, on a 15-minute schedule. A repository can opt out withAUTO_RELEASE=off. Tagging and the GitHub release are done by the reusableauto-tagworkflow. - Owner direction, 2026-11-15, for the weather work: “We are not releasing a V1 yet so you have full authority to keep on merging for patches, hot fixes and minor bumps. You can automatically deployed you do not need me.” Then, once the app existed: “It’s just staging to main.” So an agent the owner has authorised merges feature and fix PRs into
stagingwhen the merge gate is met, and never merges or edits astagingto default-branch release PR, which the app handles. This is the owner’s message to one session, not a repository rule; the org file still says only the owner releases, or an agent the owner has authorised. - The merge gate. Merge only when the work is complete, CI is green, it is verified at runtime where that is possible, and a code review has run with its findings resolved.
- Nothing merges while anything is red or orange (owner, 2026-11-17: “A merge should be block if anything is red or orange”). Red is a failure, error, cancellation or timeout; orange is anything still pending, neutral or waiting on action. Skipped counts as green. The rule covers every check and status on the commit, required or not. An agent never enables auto-merge or merges while one is red or orange, and never skips or disables a check to get past it. The
All checks greenworkflow enforces it: it waits for every other check and status, then fails on anything not green, and making it the required check makes every check behind it required too. Built inbundu-labs/marketing(#215,#214) andsiafuDB/cell; making it required onstagingand the default branch is an owner step, and the other repositories are still to follow. - Land through the merge queue. Required checks must trigger on
merge_group:. Usegh pr merge --squash --auto, never--admin, never a loop of merge calls; treat a 5xx or “merge already in progress” as wait. Do not require a branch to be up to date. - Never close a conflicting PR. Merge the base into the head, keep every feature, then validate and push. Never rewrite history on someone else’s branch.
- Nothing reaches the default branch outside a release. A PR into the default branch comes from
staging, arelease/*branch, orbot/registry-pin. A commit that did reach the default branch must be forward-ported, then labelledforward-ported. - Every PR names its issue.
Closes #n,Refs #norNo issue: <reason>. Bot PRs are exempt. AClosesin a PR intostagingcloses nothing until the release PR repeats it. Big work gets an issue in the repository that owns it (see the Platform playbook). - Shared workflows are pinned estate-wide at one commit SHA with a
# vX.Y.Zcomment. Actions are pinned by their full 40-character SHA. Dependabot targetsstagingand waits seven days before proposing a new version (a Semgrep rule requires it). - Deploys run on every push to the default branch. No variable decides whether they run, and a missing secret fails the deploy loudly. See the Edge and secrets section of the Platform playbook.
- A change is not done until it is released. For the weather repository, a release also needs a plain-language note in its releases page, written for the person using the app: no PR numbers, no code or model names.
- Follow every change all the way through (owner, 2026-11-17). As each change lands in
stagingand its checks pass there, release it straight to production; do not wait for several PRs to batch up.stagingis the checkpoint (does it build and work with the rest of the app); the release is followed by a final check against production. Nothing is left as a draft.
How to ship a change
Section titled “How to ship a change”- Open or update the issue. Branch from
staging. Open a draft PR intostagingthat names the issue. - Run the repository’s own checks locally first (format, lint, typecheck, tests for what you changed). A push that turns CI red costs a cycle.
- When the PR is ready and every check and status is green (none red or orange, required or not), enable squash auto-merge and let the queue land it. Watch CI after the merge: a red
stagingblocks the release. - Leave the release PR alone. If it is conflicted or red, fix the cause on
staging; the app re-opens it.
Open for the owner
Section titled “Open for the owner”These are conflicts between written rules. A playbook cannot choose between them.
- Merge commit or squash for the release PR. The org
AGENTS.mdin#118says to promote with a merge commit and never squash, because a squash release erased work on 2026-10-21. The orgCONTRIBUTING.mdin the same PR says squash or rebase, linear history, merge commits disabled. The older rule of 2026-10-21 says squash only, through the queue. The bot’s release PRs say auto-merge with a merge commit, and merge commits exist on default branches.nyuchi/nyuchi-api#524records that itsmerge-queue-mainruleset uses a merge method, so every release there needed a hand-appliedforward-portedlabel. This page’sconventions/overviewstub still says “Never squash on merge”. - Two release mechanisms in one repository.
nyuchi/nyuchi-apihas its ownrelease-prand tagging workflows beside the app, and its own release PR was open and conflicted when this was written.super-app-webhas arelease-prworkflow and does not use the bot lane. Which wins, per repository, is not written down. - Who may deploy. The org rule is every push to the default branch.
super-app-webdeploys by hand only (owner, 2026-10-08).nyuchi-docsdeploys through Cloudflare Workers Builds on merge. The Vercel apps deploy on push. - What the app announces and whether it tags itself is not visible from the repositories; the
nyuchi/.githubworkflows were not readable when this was written. - A check named “no agent-local files” exists on the weather repository, but no workflow carrying that text was found in the others. Some repositories track
CLAUDE.mdand some keep it untracked so the default branch never ships it. One rule is needed.