Open pull requests with three plain lines and land each one as a single commit (GST-2737) (#4438)

* WIP plain PR bodies and squash messages

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Fold PR bodies to three plain lines and land every PR as one plainly titled commit

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Expect the plain commit body in the train land tests

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Count the new policy keys in the floor tests and record the ship size change

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Let older, generated and Dependabot PRs pass the body check, and keep comments posting

The opening check now follows the same date and branch exemption as the rest of the body check, Dependabot branches are exempt, the exemption only counts for branches in this repository, a merge that cannot read the PR waits instead of refusing, and a broken policy file no longer stops comments.

Review-Finding: p1/specialist-batched#1 reader=testing
Review-Finding: p1/specialist-batched#2 reader=testing
Review-Finding: p1/red-team#1 reader=red-team
Review-Finding: p1/red-team#2 reader=red-team
Review-Finding: p1/red-team#4 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Stop re-posted PR bodies from duplicating sections, and let file names through the word check

Posting an already-folded body now replaces each section once instead of keeping the old copy beside it, and listed words inside file paths or file names, such as a test file in the Tests section, no longer count as prose.

Review-Finding: v2/outside-voice#3 reader=outside-voice
Review-Finding: v2/adversarial-native#2 reader=adversarial-native
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Describe the folded three-line PR body in the skills guide and the prose lint help

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
Garry Tanandcapy-ai[bot] authored and GitHub committed 2026-11-17 13:14:33 +00:00
1 parent aeb74eb00b
commit c53b15c48d
47 files changed
+1182 -208

No files matched your search

+26 -5
View File
@@ -32,6 +32,7 @@
* (loaded only on the train paths).
*/
import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import { ghSpawnSync } from '../lib/gh-poll';
import { EXIT, exitTableHelp, formatResult } from '../lib/headless-artifacts';
@@ -66,7 +67,7 @@ const HELP = `gstack-ship-queue — the shared merge queue's protocol steps (doc
verify --pr <n> --screen (train policy) the PR head's screen verdict read from its run (SCREEN_VERDICT)
verify --post-merge <sha> [--timeout <s>] wait for every check run at a merged commit to settle: POST_MERGE: green|red|pending
and one CHECK: line per workflow; resumable, default timeout 2700 s
land --pr <n> --pin <sha> [--accept-gate-disposition <id>]... [--repair] [--dry-run] [--allow-repo-commands] [--break-lock]
land --pr <n> --pin <sha> [--accept-gate-disposition <id>]... [--repair] [--dry-run] [--allow-repo-commands] [--break-lock] [--body-file <f>]
merge: direct: merge the PR at its own green head (receipt and READY at the pin, no stamp
files, checks green, mergeable clean), verify the tree, write a land note; a stale base
runs land.merged_checks, repo commands, only with --allow-repo-commands (never --dry-run);
@@ -74,9 +75,12 @@ const HELP = `gstack-ship-queue — the shared merge queue's protocol steps (doc
--repair: while frozen, land the one repair PR the freeze admits (recorded under the lock);
an owner gate disposition the approval store applies at the pin merges only when the
lander passes --accept-gate-disposition <its approval id> (docs/ship-policy.md#gate-dispositions)
land --pr <n> [--dry-run] [--no-wait] [--timeout <min>] [--break-lock [--break-train-lock]] [--allow-repo-commands]
land --pr <n> [--dry-run] [--no-wait] [--timeout <min>] [--break-lock [--break-train-lock]] [--allow-repo-commands] [--body-file <f>]
the merge step: lock, merge the base, stamp (fragments folded), push the stamp commit,
wait for its checks, squash with --match-head-commit, confirm the base tree; resumable
Both forms merge as one commit titled "<PR title> (#n)" whose body is the PR body's opening
lines (at most 3) plus the branch's trailers; --body-file replaces the opening lines; METHOD,
SUBJECT and BODY lines show it first (docs/writing-prs.md#the-commit-on-main)
land --pr <n> --repair after QUEUE_LAND_DRIFT: open the PR that gives the merge outside land its own
release; /ship and land it, which releases the lock
land --census what land would do with every open PR (read-only)
@@ -90,6 +94,12 @@ const HELP = `gstack-ship-queue — the shared merge queue's protocol steps (doc
refs/notes/gstack-land lock), ready under changelog_fragments (its READY receipt note) and merge trains.
${exitTableHelp()}`;
/** land --body-file: the plain lines that replace the PR body's opening in the merge commit; land scans them like the rest of the message. */
function landBody(file: string | undefined): { text?: string } | { error: string } {
if (file === undefined) return {};
try { return { text: fs.readFileSync(path.resolve(file), 'utf8') }; } catch (e) { return { error: `cannot read --body-file ${file}: ${(e as NodeJS.ErrnoException).code ?? String(e)}` }; }
}
function flag(args: string[], name: string): string | undefined {
const i = args.indexOf(name);
return i >= 0 ? args[i + 1] : undefined;
@@ -173,10 +183,19 @@ function gateAhead(ctx: QueueContext, args: string[]): number {
});
}
/** Which land form this checkout's base policy takes, so a lander never guesses between the two. */
function landFormLine(repoRoot: string): string {
const loaded = loadBasePolicy({ repoRoot, base: resolveBaseBranch(repoRoot), gh: () => ({ ok: false, out: '', err: 'no gh in --help' }) });
if ('message' in loaded) return '';
return loaded.policy.merge === 'direct'
? `\nThis repository (merge: direct): land each READY PR with gstack-ship-queue land --pr <n> --pin <the READY's head sha>.\n`
: `\nThis repository (merge: ${loaded.policy.merge}): land with gstack-ship-queue land --pr <n>${loaded.policy.train ? ', or train land for a built train' : ''}; --pin is the merge: direct form.\n`;
}
async function main(argv: string[]): Promise<number> {
const [cmd, ...args] = argv;
if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { process.stdout.write(HELP + '\n'); return cmd ? EXIT.ok : EXIT.usage; }
const probe = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8', timeout: 15_000 });
if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { process.stdout.write(HELP + '\n' + (probe.status === 0 ? landFormLine(probe.stdout.trim()) : '')); return cmd ? EXIT.ok : EXIT.usage; }
if (probe.status !== 0) return usage('not inside a git repository');
const repoRoot = probe.stdout.trim();
const gh = (a: string[]) => { const r = ghSpawnSync(a, { cwd: repoRoot, encoding: 'utf8', timeout: 60_000 }); return { ok: r.status === 0, out: r.stdout ?? '', err: r.stderr ?? (r.error ? String(r.error.message) : '') }; };
@@ -196,15 +215,17 @@ async function main(argv: string[]): Promise<number> {
const l = await import('../lib/ship-queue-land');
if (args.includes('--census')) return finish('land', l.census(ctx));
if (!pr || !/^\d+$/.test(pr)) return usage('land needs --pr <number> (or --census)');
const body = landBody(flag(args, '--body-file'));
if ('error' in body) return usage(body.error);
if (args.includes('--pin')) {
const pin = flag(args, '--pin') ?? '';
if (!/^[0-9a-f]{40,64}$/.test(pin)) return usage('--pin needs the full head sha the READY names');
const accept = acceptedIds(args);
if (accept.bad !== undefined) return usage(`--accept-gate-disposition needs an approval id (a-<12 hex>), not ${JSON.stringify(accept.bad)}`);
return finish('land', (await import('../lib/ship-queue-land-direct')).landDirect(ctx, { pr, pin, acceptGateDispositions: accept.ids, dryRun: args.includes('--dry-run'), allowRepoCommands: args.includes('--allow-repo-commands'), breakLock: args.includes('--break-lock'), repair: args.includes('--repair') }));
return finish('land', (await import('../lib/ship-queue-land-direct')).landDirect(ctx, { pr, pin, body: body.text, acceptGateDispositions: accept.ids, dryRun: args.includes('--dry-run'), allowRepoCommands: args.includes('--allow-repo-commands'), breakLock: args.includes('--break-lock'), repair: args.includes('--repair') }));
}
const timeout = flag(args, '--timeout');
return finish('land', l.land(ctx, { pr, repair: args.includes('--repair'), dryRun: args.includes('--dry-run'), noWait: args.includes('--no-wait'), breakLock: args.includes('--break-lock'), breakTrainLock: args.includes('--break-train-lock'), allowRepoCommands: args.includes('--allow-repo-commands'), waitTimeoutMin: timeout && /^\d+$/.test(timeout) ? Number(timeout) : undefined }));
return finish('land', l.land(ctx, { pr, body: body.text, repair: args.includes('--repair'), dryRun: args.includes('--dry-run'), noWait: args.includes('--no-wait'), breakLock: args.includes('--break-lock'), breakTrainLock: args.includes('--break-train-lock'), allowRepoCommands: args.includes('--allow-repo-commands'), waitTimeoutMin: timeout && /^\d+$/.test(timeout) ? Number(timeout) : undefined }));
}
if (!pr || !/^\d+$/.test(pr)) return usage(`${cmd} needs --pr <number>`);
const gateExit = flag(args, '--gate-exit');