From 1efa37957db2c4d2b45c5d07ea947e75c279022f Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 16 Oct 2026 11:28:32 +0200 Subject: [PATCH] Playbooks 07 and 08: is the coast clear? Hold a push while a release branch in flight shares its files; the glossary's release branch The operator, 2026-10-16: the file module waited for feature 57's release branch, which changes four of the same controller files. --- 00-META/glossary.md | 4 ++++ 00-META/process/07-feature-branches.md | 28 +++++++++++++++++++++++++- 00-META/process/08-small-fixes.md | 4 +++- 3 files changed, 34 insertions(+), 2 deletions(-) diff --git a/00-META/glossary.md b/00-META/glossary.md index c64dad16..3807c0b7 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -364,6 +364,9 @@ planner, the rollout). **Downstream of** Module, Core, Health and repair and Dat - **delivery group** — two or more deliveries sharing a pull request head branch name across the mesh's repositories, delivered as one unit in an order declared (`after:`) or inferred by the planner. One level: a group holds deliveries, never groups. Its state is derived from its members, never set. +- **release branch** — a branch other than `main`, shared by name across repositories, that collects a feature's + merged work and is brought into `main` as one delivery (design 57's `feat/57-config-and-provisioning`). While it + is in flight, a change that touches its files waits for it (playbook 07, *Is the coast clear?*). - **delivery plan** — what a delivery does to the mesh: its **build plan** (the modules it moves and their dependents, in tiers), its **deploy plan** (per node, what it receives and what waits for a person) and its verdict (the composed nodes, the replays). Computed by the controller's planner from a @@ -682,6 +685,7 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical. | release | a person letting a held delivery go on | **release** | Change and delivery | | | taking a consumer off a licence | **unbind** (verb `release`, to rename) | Identity and access | | | a copy of a work an engine can fetch | **media release** | Media | +| | a branch brought into `main` as one delivery | **release branch** | Change and delivery | | gate | the judgement on a delivery's first node | **first-node gate** | Change and delivery | | | the pull request status | **merge gate** | Change and delivery | | | a failed step stopping its module's later steps (ADR 0136) | *a failed step holds its module* | Placement | diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 9780a22b..1fe4c367 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -121,9 +121,32 @@ never into the running one, unless it blocks the running one. report, and the round does not wait for it. What a round asks is only what makes the change wrong against its issues and its decisions. +## Is the coast clear? + +Before the push of phase 3 (and of a small fix, playbook [08](08-small-fixes.md) step 5), the lead checks, for every +repository the change touches, whether a **release branch** is in flight there: a branch other than `main` that +collects a feature's merged work to bring it into `main` as one delivery. + +1. **Look for one.** A pull request into `main` whose head is a release branch (`gitea.gitea_open_pulls`), a + release branch holding merged work that `main` does not have yet (`git log origin/main..origin/`), or + a delivery plan of that release branch still running (`mesh-controller.plans`). +2. **Compare the files.** `git diff --name-only origin/main...origin/` against the files the + change touches. +3. **Overlap: hold.** If the release branch touches a file the change touches, nothing is pushed into that repository + until the release branch's delivery plan is done. Then the feature branch is brought up to the new `main`, the unit + tests run again, and the push follows. The hold is on the wait list (its bound: the release branch's delivery plan), + and is said to the operator with what the change waits for. +4. **No overlap: go on.** A release branch in another repository, or one that shares no file with the change, does not + hold it; its merge joins the merge window as any other (ADR 0276). + +Merging beside a release branch still in flight would make its lead resolve someone else's conflicts in the +middle of it, and could send part of the change with its delivery (2026-10-16: the file module's +controller part touched four files feature 57's release branch also changed). + ## Phase 3 — Check (no review) -1. **Push every feature branch and open one pull request per repository, together.** The integration tests +1. **Push every feature branch and open one pull request per repository, together, once the coast is clear** + (above). The integration tests run only in the merge check (the operator, 2026-10-16), never before. Pull requests in two or more repositories that share the branch name are one delivery group (ADR 0239 §2). Where a session pushes through the forge tool `gitea_commit` (one commit on the forge's current base), the @@ -178,6 +201,7 @@ on, with when it started and its bound. | the review | 15 minutes a round | ask the reviewer; stop at round 3 | | a merge check | 15 minutes | read the build queue (`mesh-controller.queue`) and the check's log | | the ready mark | 15 minutes after the acceptance is shown | the reviewer marks it, or the lead does | +| a release branch in flight that shares files | its delivery plan done | report it every ten minutes; bring the branch up to `main` after | | a merge after ready | 5 minutes after the checks pass | read `mesh-delivery.show` for the delivery | | a delivery plan | its class's budget (`mesh-delivery.times`), at most 30 minutes | read `mesh-controller.plans`, then `mesh-delivery.stalled` | @@ -242,6 +266,8 @@ issues in `fixing` that nobody works on reads to the operator as stuck work. review rules; `issue-tracker.list` with `flag: abandoned` lists issues left in `fixing` with nobody on them. - A pull request reviewed and green but not marked ready for more than 15 minutes is a lead that did not mark it. +- A pull request opened into a repository whose release branch was in flight and shared a file with it is the failure of + *Is the coast clear?*; the lead's report names the check it made before the push. - A step that adds or changes a module marked ready with no integration test that starts the module whole is the failure of phase 3's fourth step. - A bed run from `.work//mesh-lab` that fails naming a `.work///…` path it cannot find is a diff --git a/00-META/process/08-small-fixes.md b/00-META/process/08-small-fixes.md index a4cd1678..c56ce817 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -35,7 +35,9 @@ one delivery**. Everything before the push is local and fast. done-when is opened as an issue of its own, never asked as a change). The reviewer's findings go back to the same agent that wrote the fix, continued by its id, so the fix keeps its context. A playbook or design edit of a few lines may skip the reviewer: the operator's word on the pull request is its review, and the lead marks it ready on that word. -5. **Push once and open the pull request.** The forge's merge check runs the integration tests, the only +5. **Push once and open the pull request, once the coast is clear** (playbook [07](07-feature-branches.md), *Is + the coast clear?*: no release branch in flight in the repository that shares a file with the fix). The forge's merge + check runs the integration tests, the only place they run (the operator, 2026-10-16). A failed check goes back to the same agent with the failure, and the reviewer reads only the change it makes. 6. **The reviewer marks it ready at once** (for an edit that skipped the reviewer, the lead, on the