rarestg/stacked-diffs

Stacked Diffs

Break large work into a chain of small, dependent PRs. Each PR is one logical unit — easy to review, test, and revert. The stack merges bottom-up into main.

Core Rule

Move to a new stacked branch whenever the current diff reaches a natural boundary. Do not accumulate a large changeset on one branch. Commit, push, open a PR, then branch off and keep going.

A natural boundary is any of:

• A self-contained logical step is complete (new type, new endpoint, new test file)
• The diff is approaching ~200–400 changed lines
• The next change serves a different concern than the current one

When to Stack

Stack when the work has multiple logical steps that build on each other:

• Scaffolding + core logic + edge cases
• Data model + API endpoint + UI integration
• Refactor + feature that depends on the refactor

Do NOT stack independent, unrelated changes — use separate PRs instead.

Workflow

1. Plan the stack

Before writing code, sketch the stack — an ordered list of diffs, each one logical step:

Stack: <feature>
  01-<description> — <what and why>
  02-<description> — <what and why>
  03-<description> — <what and why>

The plan can evolve. If a diff grows too large or a new step emerges during implementation, split on the fly.

2. Execute each diff

Work through the stack sequentially. For each diff:

# First diff branches from main
git checkout main && git pull && git checkout -b <feature>/01-<description>

# Subsequent diffs branch from the previous
git checkout -b <feature>/02-<description>

When the diff is complete, commit, push, and open a PR:

git add <files> && git commit -m "<message>"
git push -u origin <branch>

# First PR targets main
gh pr create --base main --title "<title>" --body "$(cat <<'EOF'
...
EOF
)"

# Subsequent PRs target the previous branch
gh pr create --base <feature>/01-<description> --title "<title>" --body "$(cat <<'EOF'
...
EOF
)"

Then immediately check out a new branch for the next diff and keep working.

3. PR descriptions

Include a stack table so reviewers see the full chain:

## Stack

PR N/M for <feature>.

| # | PR | Description |
|---|-----|-------------|
| 1 | #<number> | <description> |
| 2 | **this PR** | <description> |

## Changes

<what this specific PR does>

Update earlier PRs with the table as new PRs are created.

4. Updating earlier diffs

If an earlier diff needs changes, rebase all downstream branches:

git checkout <feature>/01-<description>
# ... make changes, commit, push ...

git checkout <feature>/02-<description>
git rebase <feature>/01-<description>
git push --force-with-lease

git checkout <feature>/03-<description>
git rebase <feature>/02-<description>
git push --force-with-lease

Always --force-with-lease, never --force.

Exception: review-comment cleanup on an active PR stack may intentionally land in a new follow-up PR above the current stack top instead of amending an older reviewed branch. Use the github-review-workflow queue when original review threads need replies that reference that follow-up PR.

Branch Naming

Pattern: <feature>/<NN>-<short-description>

auth/01-user-model
auth/02-login-endpoint
auth/03-session-middleware

Notes

• Work one diff at a time — do not batch-create all branches upfront.
• If a diff grows beyond ~400 lines, split it before pushing.
• To extend an existing stack, branch from the current top.