diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 42db0bdc3..4a189b6e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1085,3 +1085,5 @@ When you're happy with your skill edits: ``` This runs tests, reviews the diff, triages the comments of every review bot you configured (Greptile's with 2-tier escalation), manages TODOS.md, bumps the version, and opens a PR. See `ship/SKILL.md` for the full workflow. + +A maintainer then merges the PR with `gstack-ship-queue land`. To merge the same way in your own repository, even with one maintainer, see [Merge with land](docs/ship-policy.md#land-normal). diff --git a/changelog.d/land-normal-merge.md b/changelog.d/land-normal-merge.md new file mode 100644 index 000000000..b76774f3a --- /dev/null +++ b/changelog.d/land-normal-merge.md @@ -0,0 +1 @@ +- **The ship policy guide now explains how to merge any pull request with `gstack-ship-queue land`, even in a repository with one maintainer.** It names the two policy keys land needs before it will run, lists what land already checks, gives a pinned `gh pr merge` fallback for repositories that can't use land yet, and covers four common traps. CONTRIBUTING.md links to it. diff --git a/docs/ship-policy.md b/docs/ship-policy.md index 8e85deb19..1e602b175 100644 --- a/docs/ship-policy.md +++ b/docs/ship-policy.md @@ -2589,6 +2589,127 @@ tree, taking no lock and pushing nothing. ### `land --pin`: merge at the PR's own green head (`merge: direct`) + +#### Merge with land, even in a repo with one maintainer + +`gstack-ship-queue land --pr --pin ` is the normal way to merge a PR +in any repository that uses gstack, including one with a single maintainer and +nobody coordinating merges. Whoever merges runs it, with `` set to the +commit they reviewed. It merges that exact commit or nothing, and afterward it +checks that main holds what was reviewed. + +**Set two keys first.** Land reads `.gstack/ship-policy.json` from the base +branch and refuses with `QUEUE_NOT_READY` unless both are set +(`landDirect` in `lib/ship-queue-land-direct.ts`). Neither is on by default +(`DEFAULT_POLICY` in `lib/ship-policy.ts` has `merge: "train"` and +`changelog_fragments: null`), which is why land refuses in most repositories +until someone adds them: + +- `"merge": "direct"` tells gstack each PR merges on its own, at its own green + head. Land refuses under any other value. +- `"changelog_fragments"` makes each PR carry its changelog entry as a file in + `changelog.d/` instead of editing VERSION or CHANGELOG.md, so two PRs never + fight over the next version. `gstack-ship-queue ready` writes the READY note + land needs only when this key is set, so land refuses `merge: direct` + without it. + +The smallest policy that works: + +```json +{ + "merge": "direct", + "changelog_fragments": { "dir": "changelog.d" }, + "min_gstack_version": "1.95.0.0" +} +``` + +`min_gstack_version` is required because `merge` arrived in gstack 1.95.0.0, +and an older gstack has to refuse the file by name rather than misread it. +Every key you leave out keeps its default. Check the file with +`gstack-ship-policy validate`. Land reads the policy from the base branch, so +the PR that adds it merges by the [fallback](#land-fallback) below; land works +from the next PR on. With PRs already open, run `land --census` first +([migrating to fragments](#migrating-to-fragments)). + +**Each PR, start to finish:** + +```bash +/ship # review, tests, the changelog.d entry, the receipt in the PR body +gstack-pregate run --allow-repo-commands # once CI is green at the head +gstack-ship-queue ready --pr 42 --no-screen # records the READY note land looks for +gstack-ship-queue land --pr 42 --pin +``` + +Add `--allow-repo-commands` to `land` when the policy lists +`land.merged_checks` (below). Versions don't move per PR. When you want a +release, `gstack-release-stamp open` opens a release PR that sets the version +and folds the `changelog.d` entries into CHANGELOG.md, and you land it the +same way ([the release PR](#release-stamp)). + +**What land already checks, so you don't.** Before it merges, land refuses +unless: + +- the PR's head is still the pin (`QUEUE_LAND_PIN_MOVED`); +- the PR is open, targets the base branch, and comes from this repository, not + a fork; +- every check at the pin is green, with none pending; +- GitHub reports the PR `MERGEABLE` and `CLEAN`; +- the /ship receipt in the PR body and a READY note are both bound to the pin. + +After merging, it checks that main's tree is exactly the pin merged onto the +commit before it (`QUEUE_LAND_UNVERIFIED` otherwise). A script that reads +these before calling land adds nothing; read land's output instead. Every +check, with its refusal code, is in [the table below](#land-direct-contract). + + +**When a repo can't use land.** Check the receipt with the read-only half of +land, then merge pinned to the same commit: + +```bash +gstack-ship-queue verify --pr 42 --pin # receipt bound to , gate dispositions accepted; merges nothing +gh pr view 42 --json state,baseRefName,headRefOid,mergeable,mergeStateStatus +gh pr checks 42 # every check passed, none pending +gh pr merge 42 --squash --match-head-commit \ + --subject " (#42)" \ + --body "" +gh pr view 42 --json state,mergeCommit # MERGED, with its merge commit +``` + +`verify --pin` doesn't read CI or GitHub's merge state, so the two `gh` +reads replace those checks. `--match-head-commit` makes GitHub refuse the +merge if anyone pushed after you checked. Use `--merge` instead of +`--squash` where branch rules allow only merge commits. Keep the subject and +body plain: they become main's history. + + +**Known traps.** + +- **GitHub merge queues.** Land doesn't support them. With a queue on the base + branch, `gh pr merge` only queues the PR and can exit 0 even when the queue + later drops it, so confirm the PR reads `MERGED` instead of trusting the + exit code. +- **Migration collisions.** Two PRs can add the same migration number and both + pass CI, and land doesn't look at migrations. The check is + `gstack-pregate regate --against --bundle --pr ` + with the policy's `migrations` key set, which compares the branch's new + numbers with main and every open PR ([regate](pregate.md#regate)). +- **`bump`.** Without `changelog_fragments`, the default `bump: ask` stops + an unattended /ship at `BUMP_ANSWER_REQUIRED`, so a repo on the fallback + sets `"bump": "patch"`. With fragments a PR never writes a version and + `bump` only sizes the release (PATCH under `patch`, MICRO otherwise), and + `bump: never` is refused next to `changelog_fragments`, so drop it before + switching. +- **CI results belong to one commit.** Checks, the /ship receipt and the READY + note each name a sha, so after any push, a merge of main included, land + refuses until checks are green and `ready` has run at the new head (the + receipt itself can [carry across a base merge](#carrying-a-receipt-across-a-base-merge-or-a-test-only-fix)). + A `pull_request` CI run tests GitHub's merge commit rather than your branch, + so on a branch behind main `gstack-ci-carry` reports `tree_mismatch`: + dispatch the workflow on the branch (`gh workflow run --ref `). + + +#### Every check land makes + Under `"merge": "direct"` in the base policy, the Captain merges one READY PR at a time with `gstack-ship-queue land --pr --pin `, where `` is the head the READY names. There's no train and no stamp commit. GitHub's