# Stacked pull requests (MergeTempo)

Instructions for a coding agent (Claude Code, Cursor, Copilot, Codex, or any
assistant that can open pull requests) on how to ship a change as a **light
stack** of small, dependent PRs that MergeTempo can review in order.

Drop this file in your repo (e.g. `.mergetempo/stacked-prs.md`, or paste it into
your `AGENTS.md` / `.cursorrules`) and tell your agent to follow it whenever a
change is too big for one PR, or naturally splits into dependent steps.

---

## Why stack

One giant PR is hard to review and hard to coach on. A stack breaks the work
into a readable sequence — schema, then API, then UI — where each PR is small
enough to review well, and each builds on the one before it.

MergeTempo is built to review stacks: it reads the hint below, shows each PR's
place in the stack, and links them in merge order. **Review and merge top to
bottom, in MergeTempo.**

## The mechanic (keep it light)

```
develop ── branch-1 ── branch-2 ── branch-3
            PR #101     PR #102     PR #103
             (base:      (base:      (base:
              develop)    branch-1)   branch-2)
```

- Each branch is created **from the previous branch**, not from trunk.
- Each PR **targets the branch above it**: PR #101 → `develop`, PR #102 →
  `branch-1`, PR #103 → `branch-2`.
- When PR #101 merges and its branch `branch-1` is deleted, GitHub
  **automatically retargets** the open PR #102 onto `develop`. Then #102 merges,
  #103 retargets onto `develop`, and so on. You never rewrite a base by hand.

> Make sure the merged head branch is deleted so the retarget fires — enable
> "Automatically delete head branches" in the repo settings, or delete it on
> merge. MergeTempo merges top to bottom, which keeps this in order.

## The convention

Every PR in the stack ends its description with a **stack footer**: one
machine-readable HTML comment plus a human-readable list. The comment always
points at the **root PR** (the first one you opened) and lists the whole stack
in order. MergeTempo reads the comment; humans read the list.

```
<!-- mergetempo-stack root=#<ROOT> order=<N1>,<N2>,<N3> -->
### 📚 Stacked PR — <POSITION> of <TOTAL>

Part of the stack rooted at #<ROOT>. Review in order in MergeTempo:

1. #<N1> — <title 1> → `<base branch 1>`
2. #<N2> — <title 2> → `<base branch 2>`
3. #<N3> — <title 3> → `<base branch 3>`

> Each PR targets the branch above it. As they merge, GitHub retargets the next
> onto `<trunk>` automatically. Please review and merge top to bottom.
```

Rules for the footer:

- `root=#<ROOT>` is the number of the **first PR you opened** in the stack. It
  never changes for the life of the stack.
- `order=` is the comma-separated PR numbers, **root first**, in merge order.
- Bold the current PR's line and append `(this PR)` so a human knows where they
  are.
- The comment is what MergeTempo parses — keep `root=` and `order=` accurate.
  The prose is for reviewers on GitHub; keep it consistent but it is not parsed.

## Workflow

1. **Split the work** into an ordered sequence of small, self-contained steps.
2. **Create the first branch** from trunk (`develop`/`main`), commit step 1,
   push, and open PR #1 targeting trunk. Note its number — this is the **root**.
3. **For each next step**, branch from the previous branch, commit, push, and
   open a PR targeting the previous branch.
4. **Once every PR exists**, you know the full `order`. Update the footer of
   **every** PR in the stack so each one carries the same `root` and `order` and
   its own `POSITION`. (Add the footer as you go, then do a final pass to fill in
   later PR numbers.)
5. **Do not** manually change a PR's base after merges — let GitHub retarget.
6. Hand the stack to reviewers in **MergeTempo**; it will show the order.

## Example (`gh` CLI)

```bash
# Step 1
git switch -c feat/users-schema develop
git commit -am "feat: users schema"
git push -u origin feat/users-schema
gh pr create --base develop --head feat/users-schema \
  --title "feat: users schema" --body "$(cat pr1-body.md)"   # → #101 (root)

# Step 2 — branch from the previous branch, target it
git switch -c feat/users-api feat/users-schema
git commit -am "feat: users API"
git push -u origin feat/users-api
gh pr create --base feat/users-schema --head feat/users-api \
  --title "feat: users API" --body "$(cat pr2-body.md)"      # → #102

# Step 3
git switch -c feat/users-ui feat/users-api
git commit -am "feat: users UI"
git push -u origin feat/users-ui
gh pr create --base feat/users-api --head feat/users-ui \
  --title "feat: users UI" --body "$(cat pr3-body.md)"       # → #103

# Final pass: set every PR's footer with root=#101 order=101,102,103
gh pr edit 101 --body "$(cat pr1-body.md)"
gh pr edit 102 --body "$(cat pr2-body.md)"
gh pr edit 103 --body "$(cat pr3-body.md)"
```

Example footer for PR #102 (`pr2-body.md`):

```
<!-- mergetempo-stack root=#101 order=101,102,103 -->
### 📚 Stacked PR — 2 of 3

Part of the stack rooted at #101. Review in order in MergeTempo:

1. #101 — Users schema → `develop`
2. **#102 — Users API → `feat/users-schema` (this PR)**
3. #103 — Users UI → `feat/users-api`

> Each PR targets the branch above it. As they merge, GitHub retargets the next
> onto `develop` automatically. Please review and merge top to bottom.
```

That's it — light stacks, no extra tooling, reviewed in MergeTempo.