diff --git a/docs/ship-policy.md b/docs/ship-policy.md index 249199f55..985534670 100644 --- a/docs/ship-policy.md +++ b/docs/ship-policy.md @@ -455,6 +455,7 @@ gstack-ship-queue wave plan # read-only: QUE gstack-ship-queue wave build --area ship --prs 41@,42@,43@ gstack-ship-queue wave build --wave --continue # after resolving a conflict in the printed worktree gstack-ship-queue wave build --wave --drop 42 # rebuild without #42 as a new wave +gstack-ship-queue wave build --wave --release # end the wave unlanded; its PRs ride alone gstack-ship-queue wave status [--wave ] gstack-ship-queue wave settle --wave [--dry-run] # after the wave PR merged ``` @@ -489,15 +490,20 @@ gstack-ship-queue wave settle --wave [--dry-run] # after the wave 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 - `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 ` and `train build` read the wave record for a `wave/` 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. diff --git a/lib/ship-queue-train-record.ts b/lib/ship-queue-train-record.ts index 1435d61a7..e372ebf9a 100644 --- a/lib/ship-queue-train-record.ts +++ b/lib/ship-queue-train-record.ts @@ -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; diff --git a/lib/ship-queue-wave.ts b/lib/ship-queue-wave.ts index 8b55cba72..4a081aab0 100644 --- a/lib/ship-queue-wave.ts +++ b/lib/ship-queue-wave.ts @@ -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 `, '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 --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/: 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 [--continue | --drop ] [--dry-run] + wave build --wave [--continue | --drop | --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 ] records, the branch chain, each constituent's GitHub head wave settle --wave [--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@,... or --wave '); if (wave && flag(rest, '--prs')) return usage('pass --prs for a new wave or --wave for an existing one, not both'); - if ((drop !== undefined || cont) && !wave) return usage('--continue and --drop need --wave '); - 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 '); + 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) { diff --git a/test/ship-queue-wave.test.ts b/test/ship-queue-wave.test.ts index 136faad90..82254ccb4 100644 --- a/test/ship-queue-wave.test.ts +++ b/test/ship-queue-wave.test.ts @@ -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']);