Stacked PRs

Who this applies to

Team members with write access to FoundationDB/fdb-record-layer (check your own access with gh api repos/FoundationDB/fdb-record-layer --jq .permissions.push). External contributors without upstream write access must use a fork and cannot use stacked PRs.

Branch location and naming convention

In order for stacked pull requests to work, branches must live directly on FoundationDB/fdb-record-layer, never on a personal fork.

As a team-wide convention, branch names must be namespaced as follows:

apple/«github-username»/**

For example, apple/arnaud-lacurie/topic1/step2. This naming scheme avoids collisions with other contributors’ branches on the shared upstream repository and keeps personal work clearly attributed.

Why upstream branches instead of a fork

A pull request’s base branch must exist in the same repository as the PR itself. A PR opened from a fork can only ever target a branch that exists upstream (typically main); it cannot chain onto another of your own branches, because that branch lives only on the fork. Working directly on upstream branches is what makes GitHub’s native support for stacked-PR chaining and coordinated stack merges possible.

Setup (once per clone)

gh extension install github/gh-stack
gh repo set-default FoundationDB/fdb-record-layer

The default-repo setting matters even when a remote named upstream already exists. Without it, gh stack and gh pr commands may resolve PR numbers against a fork remote (for example, origin) instead of upstream. If you would rather not change the default, pass --repo FoundationDB/fdb-record-layer on each gh pr and gh api invocation instead.

Common workflows

• To start a new stack, use gh stack init apple/«github-username»/«topic»/step1 apple/«github-username»/«topic»/step2 …, which adopts existing branches or creates new ones.
• To add a layer on top of the current stack, use gh stack add apple/«github-username»/«topic»/stepN.
• To push the whole stack and open or update its PRs, use gh stack submit. (Also follow the “Project conventions when submitting” below.)
• To link branches or PRs that already exist into a stack, without adopting local tracking, use gh stack link «branch-or-pr» «branch-or-pr» …, which accepts branch names, PR numbers, or PR URLs, in bottom-to-top order.
• To keep local branches in sync with remote state, use gh stack sync.
• To rebase the whole stack (for example, onto an updated main), cascading through every layer, use gh stack rebase.
• To restructure an existing stack, use gh stack modify, which opens an interactive TUI that can drop, fold, insert, reorder, and rename branches. Changes are staged and applied together; run gh stack submit afterward to update the PRs and the stack on GitHub.
• To merge the stack, use gh stack merge. (See “Merging a stack” below.)
• To navigate a stack locally, use gh stack top / bottom / up / down / switch / checkout.
• To inspect stack state, use gh stack view, which is interactive; --short gives one line per branch and --json machine-readable output. Prefer --json when a script or agent needs to reason about the stack.
• To tear a stack down, use gh stack unstack, which removes local tracking and unstacks it on GitHub while leaving the branches and their PRs intact. --local drops only the local tracking, leaving GitHub alone.

Project conventions when submitting

• New PRs must be drafts (see AGENTS.md). The interactive editor for gh stack submit defaults new PRs to ready for review, so either switch each one with the “CREATE AS” toggle, or run gh stack submit --auto, which skips the editor and creates drafts. Never pass --open unless the human explicitly asks for PRs to be marked ready.
• PR titles feed the release notes, so the auto-generated titles from --auto usually need fixing up afterwards (gh pr edit «n» --title '…').
• gh stack submit cannot apply labels, so a freshly submitted stack will land without labels. Every PR still needs one of the required labels. To add a bug fix label, for example, use gh pr edit «n» --add-label 'bug fix'.
• gh stack submit, gh stack push, and gh stack merge all change state on GitHub. Treat them as human-initiated. Don’t run them on your own initiative, and never merge without explicit consent.