Explain how to merge any PR with gstack's land command (GST-2744) (#4377)

* Explain how to merge any PR with gstack's land command (GST-2744)

docs/ship-policy.md opens its land section with the two policy keys a repo sets first, what land checks, a pinned gh pr merge fallback and four known traps; CONTRIBUTING.md points to it.

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

* Show regate's required arguments in the migration trap (GST-2744)

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

* Add the changelog entry for the land merge guide (GST-2744)

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-16 02:50:17 +00:00
1 parent 45ee345030
commit eb0aa51c17
3 files changed
+124

No files matched your search

+2
View File
@@ -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).
+1
View File
@@ -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.
+121
View File
@@ -2589,6 +2589,127 @@ tree, taking no lock and pushing nothing.
<a id="land-direct"></a>
### `land --pin`: merge at the PR's own green head (`merge: direct`)
<a id="land-normal"></a>
#### Merge with land, even in a repo with one maintainer
`gstack-ship-queue land --pr <n> --pin <sha>` 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 `<sha>` 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 <head sha>
```
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).
<a id="land-fallback"></a>
**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 <sha> # receipt bound to <sha>, 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 <sha> \
--subject "<PR title> (#42)" \
--body "<what changed for a user, why, anything the reader must do>"
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.
<a id="land-traps"></a>
**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 <gated head> --bundle <evidence-bundle.json> --pr <n>`
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 <workflow> --ref <branch>`).
<a id="land-direct-contract"></a>
#### 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 <n> --pin <sha>`, where `<sha>`
is the head the READY names. There's no train and no stamp commit. GitHub's