From 27de1b8fc7e7aa2c9ad7dd230a2e3bef257048fa Mon Sep 17 00:00:00 2001 From: garrytan Date: Sat, 31 Oct 2026 22:27:35 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20wave=20PRs=20=E2=80=94=20drop/release?= =?UTF-8?q?=20wait=20for=20a=20closed=20wave=20PR,=20settle's=20base=20che?= =?UTF-8?q?cks,=20more=20QUEUE=5FWAVE=5F*=20cases?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- docs/ship-policy.md | 17 +++++++++-------- docs/troubleshooting.md | 29 ++++++++++++++++++----------- 2 files changed, 27 insertions(+), 19 deletions(-) diff --git a/docs/ship-policy.md b/docs/ship-policy.md index 6057641b0..1507a702b 100644 --- a/docs/ship-policy.md +++ b/docs/ship-policy.md @@ -488,8 +488,8 @@ gstack-ship-queue wave settle --wave [--dry-run] # after the wave - **Frozen heads.** Once in, a constituent's head does not move. Fixes go on the wave branch as integrator commits, which the chain check allows. A constituent that has to change goes back to its owner: `--drop ` builds - a new wave on a new branch (never a force-push; the old record is marked - superseded and its PR is closed by the integrator), refused with + a new wave on a new branch (never a force-push; the integrator closes the + old wave PR first, and the old record is marked superseded), refused with `QUEUE_WAVE_DEPENDENT` when another pin contains the dropped one. A drop that would leave fewer PRs than the minimum releases the wave instead, and `--release` does the same for a wave PR closed without merging: the record @@ -510,12 +510,13 @@ gstack-ship-queue wave settle --wave [--dry-run] # after the wave land`, `verify`, the stamp and the backstop treat it like any PR, and under `changelog_fragments` its one stamp folds every constituent's fragment into one version section. -- **After the merge.** `wave settle` finds the merged wave PR, checks main's - merge carries its head tree and walks its chain (the train's stamp commit on - top is allowed). A constituent still at its pin gets a "Landed in wave #W as - vX (sha)" comment naming any integrator commits that touched its files, and - is closed. One whose head moved after the wave froze stays open with a - comment saying its newer work did not land. Comments carry a marker, so a +- **After the merge.** `wave settle` finds the wave PR merged into the base + branch, checks that its merge commit is on that branch and carries its head + tree, and walks its chain (train land's stamp commits on top are allowed). A + constituent still at its pin gets a "Landed in wave #W as vX (sha)" comment + naming any integrator commits or hand-resolved merges that touched its + files, and is closed. One whose head moved after the wave froze stays open + with a comment saying its newer work did not land. Comments carry a marker, so a rerun posts nothing twice; `--dry-run` shows the plan. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 72dd4d6e2..ffd518809 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -4758,23 +4758,29 @@ build the wave without that PR. pushed, closed or merged after it joined (heads freeze once in), the wave branch carries a merge that is not a constituent's pin (main merged in, for example), a pin is missing from the branch, or the wave was rebuilt and this -PR is the old one. +PR is the old one. The same code refuses a constituent that targets a branch +other than the base (a stacked PR's pin carries its parent's commits), a +wave that was released, and a `--drop` or `--release` while the wave PR is +still open, since a train that already admitted it would still land it. -**Fix.** Rebuild without the moved PR, `wave build --wave --drop -`, which makes a new wave branch and PR (never a force-push); run /ship -and READY the new wave PR. The moved PR goes back to its owner and rides on its -own or in a later wave. +**Fix.** Close the wave PR if one is open, then rebuild without the moved PR, +`wave build --wave --drop `, which makes a new wave branch and PR (never a +force-push); run /ship and READY the new wave PR. The moved PR goes back to +its owner and rides on its own or in a later wave. A stacked PR rides on its +own; after a release, each constituent is READY'd on its own. ### `QUEUE_WAVE_DUPLICATE` **Meaning.** A PR would land twice or waves would nest: it is already a constituent of another live wave, `train build` was handed both a wave PR and -one of its constituents (or two waves sharing one), or a wave PR was named as a -constituent. +one of its constituents (or two waves sharing one), a wave PR was named as a +constituent, or a constituent of a live wave was READY'd or handed to `train +build` on its own. **Fix.** Keep each PR in one place: drop the separate pin from `train build`, -or rebuild one wave without the shared PR. +or rebuild one wave without the shared PR. A constituent of a live wave lands +through the wave PR. ### `QUEUE_WAVE_SIZE` @@ -4808,9 +4814,10 @@ still land the dropped code. ### `QUEUE_WAVE_NOT_MERGED` -**Meaning.** `wave settle` found no merged PR whose head branch is the wave -branch, or main's merge commit does not carry that PR's head tree, so it -cannot say the constituents landed. Nothing was commented or closed. +**Meaning.** `wave settle` found no PR merged into the base branch whose head +branch is the wave branch, its merge commit is not on the base branch, or that +merge does not carry the PR's head tree, so it cannot say the constituents +landed. Nothing was commented or closed. **Fix.** Land the wave PR through its train (`train land`), then rerun `gstack-ship-queue wave settle --wave `.