ship-queue wave: release a wave (drop under --min, or --release), and accept stacked train stamps after the last constituent

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
garrytanandcapy-ai[bot] committed 2026-10-31 21:43:00 +00:00
1 parent 939710dbd9
commit 07632cf9dc
4 files changed
+57 -17

No files matched your search

+9 -3
View File
@@ -455,6 +455,7 @@ gstack-ship-queue wave plan # read-only: QUE
gstack-ship-queue wave build --area ship --prs 41@<sha>,42@<sha>,43@<sha>
gstack-ship-queue wave build --wave <nonce> --continue # after resolving a conflict in the printed worktree
gstack-ship-queue wave build --wave <nonce> --drop 42 # rebuild without #42 as a new wave
gstack-ship-queue wave build --wave <nonce> --release # end the wave unlanded; its PRs ride alone
gstack-ship-queue wave status [--wave <nonce>]
gstack-ship-queue wave settle --wave <nonce> [--dry-run] # after the wave PR merged
```
@@ -489,15 +490,20 @@ gstack-ship-queue wave settle --wave <nonce> [--dry-run] # after the wave
constituent that has to change goes back to its owner: `--drop <pr>` 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
`QUEUE_WAVE_DEPENDENT` when another pin contains the dropped one.
`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
is marked released and every constituent can be READY'd on its own again.
- **READY and the train.** `ready --pr <wave pr>` and `train build` read the
wave record for a `wave/<nonce>` head branch (rebuilt from the notes ref on a
fresh machine; `QUEUE_WAVE_UNKNOWN` when there is none). They walk the
branch's first parents back to the recorded base: every pin must be merged
unchanged, in order, and any other merge is refused. Every constituent must
still be open at its pin. READY gains `WAVE:` and `CONSTITUENTS:` lines.
`train build` refuses a PR pinned both on its own and inside a wave
(`QUEUE_WAVE_DUPLICATE`). From there the wave PR is an ordinary slot: `train
`ready` and `train build` refuse a constituent of a live wave on its own
(`QUEUE_WAVE_DUPLICATE`), so it cannot land twice. A wave head may carry
train land's stamp commits after its last constituent, so a stamped wave
is re-READY'd like any stamped PR. From there the wave PR is an ordinary slot: `train
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.
+1 -1
View File
@@ -80,7 +80,7 @@ export interface WaveConstituent {
/** Files the integrator resolved by hand in this constituent's merge (wave build --continue); absent for a clean merge. */
resolved?: string[];
}
export type WaveState = 'conflict' | 'built' | 'pushed' | 'superseded' | 'settled';
export type WaveState = 'conflict' | 'built' | 'pushed' | 'superseded' | 'released' | 'settled';
export interface WaveRecord {
schema: 1; kind: 'wave'; nonce: string; repo_key: string; area: string; base: { ref: string; sha: string }; branch: string;
constituents: WaveConstituent[]; head: string | null; state: WaveState;
+30 -12
View File
@@ -115,27 +115,27 @@ export function groupWaves(prs: PlanPr[], areaOf: (f: string) => string, min = W
return { groups, solo: solo.sort((a, b) => Number(a) - Number(b)) };
}
export interface WaveChain { integrator: string[]; merges: string[]; stamp: string | null }
export interface WaveChain { integrator: string[]; merges: string[]; stamps: string[] }
/**
* Walk the wave branch's first parents from tip back to the recorded base. Every constituent
* must appear, in order and exactly once, as the second parent of a two-parent commit; a
* one-parent commit is an integrator commit; any other merge (main merged in, an unknown head)
* is refused. With stampBase the tip may be train land's stamp commit: parents [wave head, a
* commit already on stampBase], after every constituent.
* is refused. With stampBase, train land's stamp commits (parents [wave head, a commit already
* on stampBase]) may follow the last constituent, one per train that stamped the wave.
*/
export function waveChain(repoRoot: string, w: WaveRecord, tip: string, stampBase: string | null = null): WaveChain | { error: string } {
const r = git(repoRoot, ['rev-list', '--first-parent', '--parents', `${w.base.sha}..${tip}`]);
if (!r.ok) return { error: `cannot walk ${short(tip)} back to the wave base ${short(w.base.sha)} (${r.err.slice(0, 120)})` };
const rows = r.out.split('\n').filter(Boolean).map(l => l.split(' ')).reverse();
if (!rows.length || rows[0]![1] !== w.base.sha) return { error: `the branch at ${short(tip)} does not start at the wave base ${short(w.base.sha)}` };
const out: WaveChain = { integrator: [], merges: [], stamp: null };
const out: WaveChain = { integrator: [], merges: [], stamps: [] };
let next = 0;
for (const [i, [commit, , second, ...more]] of rows.entries()) {
for (const [commit, , second, ...more] of rows) {
if (!second) { out.integrator.push(commit!); continue; }
const want = w.constituents[next];
if (!more.length && want && second === want.head) { out.merges.push(commit!); next++; continue; }
if (!more.length && stampBase && i === rows.length - 1 && next === w.constituents.length && git(repoRoot, ['merge-base', '--is-ancestor', second, stampBase]).ok) { out.stamp = commit!; continue; }
if (!more.length && stampBase && next === w.constituents.length && git(repoRoot, ['merge-base', '--is-ancestor', second, stampBase]).ok) { out.stamps.push(commit!); continue; }
const expected = want ? `#${want.pr}'s pin ${short(want.head)}` : 'a constituent';
return { error: `${short(commit!)} merges ${short(second)}, which is not ${expected} (only constituent merges and integrator commits belong on a wave branch)` };
}
@@ -176,6 +176,7 @@ export function checkWavePin(env: TrainEnv, pr: string, info: PrInfo): { wave: W
if (!w) { rebuildFromNotes(env.ctx.repoRoot, env.remote); w = waveByBranch(env, info.headRefName); }
if (!w) return { failure: fail('QUEUE_WAVE_UNKNOWN', `#${pr}'s branch ${info.headRefName} has no wave record in local state or refs/notes/gstack-trains`) };
if (w.state === 'superseded') return { failure: fail('QUEUE_WAVE_MOVED', `wave ${w.nonce} was rebuilt as ${w.superseded_by}; READY the new wave PR`) };
if (w.state === 'released') return { failure: fail('QUEUE_WAVE_MOVED', `wave ${w.nonce} was released; its PRs ride as single slots`) };
if (!ensureCommit(env, info.headRefOid, pr)) return { failure: fail('QUEUE_PROOF_MISSING', `cannot fetch #${pr}'s head ${short(info.headRefOid)}`) };
const chain = waveChain(env.ctx.repoRoot, w, info.headRefOid, `${env.remote}/${env.ctx.base}`);
if ('error' in chain) return { failure: fail('QUEUE_WAVE_MOVED', `wave ${w.nonce}: ${chain.error}`) };
@@ -265,7 +266,7 @@ export function wavePlan(ctx: QueueContext, o: { trigger: number; min: number; m
return outOk(lines, first ? `#${first.integrator}'s owner integrates: ${buildCmd(first.area, first.prs)}` : `${Q} train build --prs <pins>`, 'none');
}
export interface WaveBuildOptions { pins?: string; area?: string; wave?: string; cont?: boolean; drop?: string; dryRun: boolean; min: number; max: number }
export interface WaveBuildOptions { pins?: string; area?: string; wave?: string; cont?: boolean; drop?: string; release?: boolean; dryRun: boolean; min: number; max: number }
export function waveBuild(ctx: QueueContext, o: WaveBuildOptions): TrainOut {
const env = setup(ctx);
@@ -273,6 +274,7 @@ export function waveBuild(ctx: QueueContext, o: WaveBuildOptions): TrainOut {
if (!o.wave) return newWave(env, o, null);
const w = loadWave(o.wave);
if (!w || !env.repo.keys.includes(w.repo_key)) return outRefused(fail('QUEUE_WAVE_UNKNOWN', `no wave record ${o.wave} in local state or refs/notes/gstack-trains`), [], `${Q} wave status`, 'none');
if (o.release) return release(env, w, [], o.dryRun);
if (o.drop) return dropFrom(env, w, o);
if (o.cont) return continueWave(env, w, o.dryRun);
if (w.state === 'conflict') return outRefused(fail('QUEUE_WAVE_CONFLICT', `wave ${w.nonce} is stopped at #${w.conflict!.pr}; resolve in ${w.conflict!.worktree}`), [], `${Q} wave build --wave ${w.nonce} --continue`, wavePath(w.nonce));
@@ -419,11 +421,25 @@ function dropFrom(env: TrainEnv, w: WaveRecord, o: WaveBuildOptions): TrainOut {
const rest = w.constituents.filter(c => c !== dropped);
const carrier = rest.find(c => git(env.ctx.repoRoot, ['merge-base', '--is-ancestor', dropped.head, c.head]).ok);
if (carrier) return outRefused(fail('QUEUE_WAVE_DEPENDENT', `#${carrier.pr}'s pin contains #${dropped.pr}'s pin, so dropping #${dropped.pr} would still land its code`), [], `drop #${carrier.pr} too, or keep #${dropped.pr}`, wavePath(w.nonce));
if (rest.length < o.min) return release(env, w, [`DROP: #${dropped.pr} from ${w.nonce} leaves ${rest.length} PR(s), under the wave minimum ${o.min}`], o.dryRun);
const out = newWave(env, { ...o, area: w.area }, w, rest.map(c => ({ pr: c.pr, sha: c.head })));
out.lines.unshift(`DROP: #${dropped.pr} from ${w.nonce}; the rebuilt wave gets a new branch and PR, and the integrator closes ${w.branch}'s PR`);
return out;
}
/** End a live wave without landing it (a drop under the minimum, or a wave PR closed unmerged): every constituent rides on its own again. */
function release(env: TrainEnv, w: WaveRecord, lines: string[], dryRun: boolean): TrainOut {
if (!LIVE.has(w.state)) return outRefused(fail('QUEUE_WAVE_MOVED', `wave ${w.nonce} is ${w.state}; only a live wave is released`), lines, `${Q} wave status --wave ${w.nonce}`, wavePath(w.nonce));
const done = [...lines, `RELEASED: ${w.nonce}: ${w.constituents.map(c => '#' + c.pr).join(',')} ride as single slots; close the wave PR on ${w.branch}`];
if (dryRun) return outOk([...done, 'DRY-RUN: no record written'], `${Q} wave build --wave ${w.nonce} --release`, wavePath(w.nonce));
if (w.conflict) { git(env.ctx.repoRoot, ['worktree', 'remove', '--force', w.conflict.worktree]); w.conflict = null; }
w.state = 'released';
w.effects.push({ at: nowIso(), what: 'released' });
w.updated_at = nowIso();
persist(env.ctx.repoRoot, [w], { remote: env.remote });
return outOk(done, `each owner READYs its PR alone: ${Q} ready --pr <n> --screen|--no-screen`, wavePath(w.nonce));
}
export function waveStatus(ctx: QueueContext, o: { wave?: string }): TrainOut {
const env = setup(ctx);
if ('exit' in env) return env;
@@ -520,9 +536,10 @@ export const WAVE_HELP = `gstack-ship-queue wave: wave PRs for merge trains (doc
the integrator branch wave/<nonce>: main plus each pin merged unchanged (train merge
rules), the wave record in refs/notes/gstack-trains, the branch pushed, a frozen notice
on each constituent; a conflict stops in a worktree under the state root
wave build --wave <nonce> [--continue | --drop <pr>] [--dry-run]
wave build --wave <nonce> [--continue | --drop <pr> | --release] [--dry-run]
resume (retry the push), continue after the integrator committed the resolution, or
rebuild without one constituent as a new wave (new branch; never a force-push)
rebuild without one constituent as a new wave (new branch; never a force-push), or
release the wave so its PRs ride alone (a drop under --min releases too)
wave status [--wave <nonce>] records, the branch chain, each constituent's GitHub head
wave settle --wave <nonce> [--dry-run] after the wave PR merged: close constituents still at their pins with the link and
version; a moved constituent stays open with a comment; resumable
@@ -563,12 +580,13 @@ export async function waveMain(ctx: QueueContext, args: string[]): Promise<numbe
if (sub === 'build') {
const drop = flag(rest, '--drop');
const cont = rest.includes('--continue');
const releaseIt = rest.includes('--release');
if (!wave && !flag(rest, '--prs')) return usage('wave build needs --prs <n>@<sha>,... or --wave <nonce>');
if (wave && flag(rest, '--prs')) return usage('pass --prs for a new wave or --wave <nonce> for an existing one, not both');
if ((drop !== undefined || cont) && !wave) return usage('--continue and --drop need --wave <nonce>');
if (drop !== undefined && cont) return usage('pass one of --continue or --drop');
if ((drop !== undefined || cont || releaseIt) && !wave) return usage('--continue, --drop and --release need --wave <nonce>');
if ([drop !== undefined, cont, releaseIt].filter(Boolean).length > 1) return usage('pass one of --continue, --drop or --release');
if (drop !== undefined && !/^\d+$/.test(drop)) return usage('--drop needs a PR number');
return print('wave build', waveBuild(ctx, { pins: flag(rest, '--prs'), area: flag(rest, '--area'), wave, cont, drop, dryRun, min, max }));
return print('wave build', waveBuild(ctx, { pins: flag(rest, '--prs'), area: flag(rest, '--area'), wave, cont, drop, release: releaseIt, dryRun, min, max }));
}
return usage(`unknown wave subcommand ${sub}`);
} catch (error) {
+17 -1
View File
@@ -156,6 +156,20 @@ describe('wave build', () => {
expect(waveJson(fx, fresh).constituents.map((c: any) => c.pr)).toEqual(['1', '2', '3', '4']);
expect(fx.repo.git('ls-remote', 'origin', `refs/heads/wave/${old}`)).not.toBe('');
}, 120_000);
test('a drop under the minimum releases the wave, and its other PRs are no longer refused as constituents', () => {
const fx = make();
const heads = threePrs(fx);
const nonce = nonceOf(queue(fx, ['wave', 'build', '--prs', heads.map((h, i) => `${i + 1}@${h}`).join(',')]).out);
readyReceipt(fx, '1', heads[0]!);
const held = queue(fx, ['train', 'build', '--prs', `1@${heads[0]}`, '--dry-run']);
expect([held.status, held.err]).toEqual([EXIT.refused, expect.stringContaining('(QUEUE_WAVE_DUPLICATE')]);
const dropped = queue(fx, ['wave', 'build', '--wave', nonce, '--drop', '3']);
expect([dropped.status, line(dropped.out, 'RELEASED:')]).toEqual([EXIT.ok, expect.stringContaining('#1,#2,#3 ride as single slots')]);
expect(waveJson(fx, nonce).state).toBe('released');
expect(queue(fx, ['train', 'build', '--prs', `1@${heads[0]}`, '--dry-run']).status).toBe(EXIT.ok);
expect(queue(fx, ['wave', 'build', '--wave', nonce, '--release']).err).toContain('only a live wave is released');
}, 120_000);
});
describe('ready and train build read the wave', () => {
@@ -235,7 +249,9 @@ describe('wave settle', () => {
const head = waveAsPr(fx, nonce);
const early = queue(fx, ['wave', 'settle', '--wave', nonce]);
expect([early.status, early.err]).toEqual([EXIT.refused, expect.stringContaining('(QUEUE_WAVE_NOT_MERGED')]);
const merge = fx.repo.git('commit-tree', `${head}^{tree}`, '-p', 'origin/main', '-m', 'wave (#10)');
const s1 = fx.repo.git('commit-tree', `${head}^{tree}`, '-p', head, '-p', 'origin/main', '-m', 'stamp 1');
const s2 = waveAsPr(fx, nonce, '10', fx.repo.git('commit-tree', `${head}^{tree}`, '-p', s1, '-p', 'origin/main', '-m', 'stamp 2'));
const merge = fx.repo.git('commit-tree', `${s2}^{tree}`, '-p', 'origin/main', '-m', 'wave (#10)');
fx.repo.git('push', '-q', 'origin', `${merge}:refs/heads/main`);
fx.write(d => { Object.assign(d.prs['10'] as any, { state: 'MERGED', mergeCommit: { oid: merge } }); (d.prs['2'] as any).headRefOid = heads[0]; });
const dry = queue(fx, ['wave', 'settle', '--wave', nonce, '--dry-run']);