Skip to content

Commit 7c27ea3

Browse files
committed
clarifications on merge behavior
1 parent 35087e6 commit 7c27ea3

8 files changed

Lines changed: 33 additions & 27 deletions

File tree

‎docs/astro.config.mjs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ export default defineConfig({
1313
integrations: [
1414
starlight({
1515
title: 'GitHub Stacked PRs',
16-
description: 'Break large changes into small, reviewable pull requests that build on each other — with native GitHub support and the gh stack CLI.',
16+
description: 'Break large changes into small, reviewable pull requests. Manage your stacks on GitHub, with the gh stack CLI, or via our APIs.',
1717
favicon: '/favicon.svg',
1818
logo: {
1919
src: './src/assets/github-invertocat.svg',

‎docs/src/content/docs/faq.md‎

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -123,11 +123,11 @@ jobs:
123123
- uses: actions/checkout@v4
124124
125125
- name: Run for the lowest unmerged PR in the stack
126-
if: github.event.pull_request.stack.base.ref == github.event.pull_request.base.ref
126+
if: github.event.pull_request.stack != null && github.event.pull_request.stack.base.ref == github.event.pull_request.base.ref
127127
run: echo "Lowest unmerged PR in the stack"
128128
129129
- name: Run for the top PR in the stack
130-
if: github.event.pull_request.stack.position == github.event.pull_request.stack.size
130+
if: github.event.pull_request.stack != null && github.event.pull_request.stack.position == github.event.pull_request.stack.size
131131
run: echo "Top PR in the stack"
132132
```
133133

@@ -154,11 +154,11 @@ Every PR in a stack must meet the same merge requirements as a PR targeting the
154154

155155
### How does merging a stack of PRs differ from merging a regular PR?
156156

157-
Stacks merge from the bottom up as a single atomic operation. When you click merge on a PR in a stack, that PR and all unmerged PRs below it land on the base branch together. PRs above remain open, and the remaining stack is automatically rebased so the next PR targets `main` directly.
157+
Stacks merge from the bottom up. When you click merge on a PR in a stack, that PR and all unmerged PRs below it land on the base branch together; PRs above remain open, and the remaining stack is automatically rebased so the next PR targets your base branch directly. With a direct merge the group lands as a single atomic operation; through a merge queue the PRs enter the queue together and are evaluated individually, from the bottom up.
158158

159159
### What happens when you merge a PR in the middle of the stack?
160160

161-
When you click merge on a PR in the middle of the stack, that PR and all unmerged PRs below it land on the base branch together as a single atomic operation, ordered from the bottom up in the resulting history. PRs above the selected one remain open. After the merge, the lowest unmerged PR is updated to target the stack base directly, and a cascading rebase runs across the remaining branches.
161+
When you click merge on a PR in the middle of the stack, that PR and all unmerged PRs below it land on the base branch together, ordered from the bottom up in the resulting history. PRs above the selected one remain open. After the merge, the lowest unmerged PR is updated to target the stack base directly, and a cascading rebase runs across the remaining branches.
162162

163163
It is not possible to merge a middle PR in isolation: the PRs below it always merge with it.
164164

@@ -206,13 +206,14 @@ When you merge a stack using the merge commit strategy, it creates **one merge c
206206
207207
### How does rebase merge work?
208208
209-
With rebase merge, the commits from each PR in the stack are replayed onto the base branch, creating a linear history without merge commits. The full set of commits lands as a single atomic operation.
209+
With rebase merge, the commits from each PR in the stack are replayed onto the base branch, creating a linear history without merge commits. The full set of commits lands on the base branch.
210210
211211
### Do all PRs get merged at once or one at a time?
212212
213-
All PRs in the stack land in a single atomic operation. When you click merge on a PR, that PR and all unmerged PRs below it are merged together onto the base branch at the same time, ordered from the bottom up in the resulting history. PRs above the selected one remain open.
213+
It depends on the merge method:
214214
215-
This applies whether or not a merge queue is enabled. With a merge queue, the same atomic landing happens once the stack's merge group reaches the front of the queue.
215+
- **Direct merge** — All the included PRs land in a single atomic operation. The selected PR and every unmerged PR below it are merged together onto the base branch at once, ordered from the bottom up. Either the whole group lands, or if any part fails, none of it does.
216+
- **Merge queue** — The PRs enter the queue together and are evaluated individually, from the bottom up. If a PR fails while in the queue, it and all its descendants are ejected, while the PRs below it are unaffected.
216217
217218
### Can I merge only part of a stack? What happens to the remaining unmerged PRs?
218219
@@ -228,15 +229,18 @@ Closing a PR in the middle of the stack will block all PRs above it from being m
228229
229230
### What happens when there is an error merging a PR in the middle of a stack?
230231
231-
Pre-merge checks run before any merge attempt, but a merge can still fail (e.g., due to an unexpected merge conflict or intermittent failure). If a failure occurs partway through, merging stops at that PR. PRs below it that successfully merged remain landed on the base branch; the failed PR and PRs above it stay open. Resolve the issue on the failed PR and retry to land the rest of the stack.
232+
Pre-merge checks run before any merge attempt, but a merge can still fail (e.g., due to a merge conflict or intermittent failure). The behavior depends on the merge method:
233+
234+
- **Direct merge** — The merge is atomic. If any part fails, the entire operation is rolled back and nothing is merged.
235+
- **Merge queue** — Because each PR is evaluated individually, a failure ejects that PR and all its descendants (the PRs stacked above it) from the queue, while the PRs below it are unaffected. You can fix the issue on the failed PR and requeue the ejected PRs.
232236
233237
### Do Stacked PRs support merge queue?
234238
235-
Yes, Stacked PRs fully support merging via merge queue. When you merge a stack through the merge queue:
239+
Yes, Stacked PRs fully support merging via GitHub merge queue. When you merge a stack through the merge queue:
236240
237-
- **All PRs in the stack are added to the queue** in the correct order, ensuring a linear sequence.
238-
- **If a PR is removed or ejected from the merge queue**, all PRs above it in the stack are also ejected and removed from the queue.
239-
- **Stacks are kept in the same merge group on a best-effort basis.** To keep a stack together, the merge queue allows the merge group to exceed its configured max size by up to 50%. If the stack is too large to fit within that buffer, it splits across consecutive merge groups: as much of the stack as fits goes into the current group, and the remaining PRs continue in subsequent groups until the full stack has landed.
241+
- **All PRs in the stack enter the queue together** in the correct order and are evaluated individually, from the bottom up.
242+
- **If a PR is ejected from the merge queue** (for example, because it fails), that PR and all its descendants are ejected too, while the PRs below it are unaffected.
243+
- **The queue makes a best-effort attempt to keep the stack together** in a single merge group. If the stack is too large to fit, it lands across consecutive merge groups: as much of the stack as fits goes into the current group, and the remaining PRs continue in subsequent groups until the full stack has landed. The stack order is preserved, so downstack PRs are merged before upstack PRs.
240244
241245
## Local Development
242246

‎docs/src/content/docs/guides/stacked-prs.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Each PR in a stack shows only the diff for its layer — the changes between its
2323

2424
## Merging a Stack
2525

26-
Merging is driven by a single action: **click Merge on the highest PR you want to land, and that PR plus every unmerged PR below it merges in one atomic operation.** You do not need to merge PRs one at a time, unless you choose to.
26+
Merging is driven by a single action: **click Merge on the highest PR you want to land, and that PR plus every unmerged PR below it are merged together, from the bottom up.** You do not need to merge PRs one at a time, unless you choose to.
2727

2828
- **To land the whole stack**, merge the **top** PR — every PR below it lands with it in a single step.
2929
- **To land part of the stack**, merge a lower PR — the PRs below it come along, and the PRs above stay open.

‎docs/src/content/docs/index.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
22
title: GitHub Stacked PRs
3-
description: Break large changes into small, reviewable, stacked pull requests with first-class GitHub support.
3+
description: Break large changes into small, reviewable, stacked pull requests on GitHub.
44
template: splash
55
hero:
66
title: GitHub Stacked PRs
7-
tagline: Break large changes into small, reviewable pull requests that build on each other — with native GitHub support and the <code>gh stack</code> CLI.
7+
tagline: Break large changes into small, reviewable pull requests. Manage your stacks on GitHub, with the <code>gh stack</code> CLI, or via our APIs.
88
actions:
99
- text: Quick Start
1010
link: /gh-stack/getting-started/quick-start/
@@ -55,7 +55,7 @@ GitHub understands stacks end-to-end: the pull request UI shows a **stack map**
5555

5656
**While the `gh stack` CLI makes the local workflow seamless, it is entirely optional.** You can create and manage Stacked PRs directly via the GitHub UI, the API, or your standard Git workflow. If you choose to use the CLI, it handles creating branches, managing rebases, pushing to GitHub, and creating PRs with the correct base branches. On GitHub, the PR UI gives reviewers the context they need — a stack map, focused diffs for each layer, and proper rules enforcement.
5757

58-
When you're ready to merge, click **Merge** on the highest PR you want to land — that PR **and every unmerged PR below it merge together in a single, atomic operation**. Merge the top PR to land the whole stack in one click, or merge a lower PR to land just part of it (the PRs above stay open). After a partial merge, the remaining PRs are automatically rebased so the lowest unmerged PR targets the updated base branch.
58+
When you're ready to merge, click **Merge** on the highest PR you want to land — that PR **and every unmerged PR below it are merged together, from the bottom up**. Merge the top PR to land the whole stack in one click, or merge a lower PR to land just part of it (the PRs above stay open). After a partial merge, the remaining PRs are automatically rebased so the lowest unmerged PR targets the updated base branch.
5959

6060
## Get Started
6161

‎docs/src/content/docs/introduction/overview.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ This ensures that every layer of the stack meets the same quality bar before it
5555

5656
### Merging Stacks
5757

58-
You can merge your entire stack, a single PR, or a portion of the stack spanning multiple PRs. When you click **Merge** on any PR, that PR **and every unmerged PR below it land together in a single atomic operation**. So you can:
58+
You can merge your entire stack, a single PR, or a portion of the stack spanning multiple PRs. When you click **Merge** on any PR, that PR and every unmerged PR below it are merged together, from the bottom up. So you can:
5959

6060
- **Land the entire stack in one click** by merging the top PR — every PR below it comes with it.
6161
- **Land part of the stack** by merging a mid-stack PR — the PRs below it come along, and the PRs above stay open.
@@ -64,10 +64,10 @@ You can't merge a PR while leaving an unmerged PR below it behind. Merging a sta
6464

6565
GitHub supports two merge methods:
6666

67-
- **Direct merge** — Merges the selected PR and all unmerged PRs below it in a single operation, as long as all conditions are met.
68-
- **Merge queue** — Works as usual but is stack-aware. For example, if the bottom PR is removed from the queue, all other PRs in the stack are also removed.
67+
- **Direct merge** — The selected PR and all unmerged PRs below it land in a single **atomic** operation. Either the whole group merges, or if any part fails, nothing is merged and the operation is rolled back.
68+
- **Merge queue** — The PRs enter the queue together and each PR is evaluated **individually**, from the bottom up. If a PR fails while in the queue, that PR and all its descendants are ejected from the queue, while prior PRs are unaffected. The queue makes a best-effort attempt to keep the whole stack in a single merge group; if the stack is too large to fit, it lands across consecutive groups. If PRs are split across merge groups, the stack order is preserved so downstack PRs are merged before upstack PRs.
6969

70-
The resulting commit history is the same as if each PR had been merged individually, starting from the bottom.
70+
In both methods, the resulting commit history is the same as if each PR had been merged individually, starting from the bottom.
7171

7272
### Merge Methods
7373

‎docs/src/content/docs/reference/graphql-api.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ An edge in a `PullRequestStackEntryConnection`.
5959

6060
## Example
6161

62-
Read a pull request's stack, its position, and every pull request in the stack:
62+
Read a pull request's stack, its position, and the first 5 pull requests in the stack:
6363

6464
```graphql
6565
{
@@ -74,7 +74,7 @@ Read a pull request's stack, its position, and every pull request in the stack:
7474
number
7575
size
7676
baseRefName
77-
entries(first: 20) {
77+
entries(first: 5) {
7878
totalCount
7979
nodes {
8080
position
@@ -92,3 +92,5 @@ Read a pull request's stack, its position, and every pull request in the stack:
9292
```
9393

9494
The pull request's own `baseRefName` is the branch it directly targets (the PR below it in the stack), while `stack.baseRefName` is the branch the entire stack ultimately targets. These differ for every PR in the stack except the bottom one.
95+
96+
`entries` is a paginated connection (ex: `first: 5` returns up to the first 5 entries). Check the `totalCount` for the full size and if a stack has more entries, page through the rest with the connection's `pageInfo`.

‎docs/src/content/docs/reference/rest-api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ gh api --method POST repos/OWNER/REPO/stacks/42/unstack
178178

179179
### The stack resource
180180

181-
The list, get, create, add, and unstack endpoints all return the stack resource:
181+
Each stack is represented by the following resource. The get, create, and add endpoints return a single stack; the list endpoint returns an array of them; and unstack returns the remaining merged stack, or `204 No Content` when the stack is dissolved.
182182

183183
| Field | Type | Description |
184184
|-------|------|-------------|

‎docs/src/content/docs/reference/webhooks.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ The `stack` object is also available in GitHub Actions workflow expressions via
109109

110110
### Optimizing CI usage
111111

112-
Because a workflow runs for every PR in a stack, you can use the `stack` fields to selectively run jobs. For example, if you only plan on merging one PR at a time, you can choose to only run CI for the lowest unmerged PR. Compare the stack's base ref to the PR's own base ref to detect the **lowest unmerged PR**, and compare `position` to `size` to detect the **top PR**:
112+
Because a workflow runs for every PR in a stack, you can use the `stack` fields to selectively run jobs. For example, if you only plan on merging one PR at a time, you can choose to only run CI for the lowest unmerged PR. Compare the stack's base ref to the PR's own base ref to detect the **lowest unmerged PR**, and compare `position` to `size` to detect the **top PR**. Note that on a standalone PR the `stack` object is `null`, so you can check that to ensure this logic only applies to stacks.
113113

114114
```yaml
115115
jobs:
@@ -119,11 +119,11 @@ jobs:
119119
- uses: actions/checkout@v4
120120

121121
- name: Run for the lowest unmerged PR in the stack
122-
if: github.event.pull_request.stack.base.ref == github.event.pull_request.base.ref
122+
if: github.event.pull_request.stack != null && github.event.pull_request.stack.base.ref == github.event.pull_request.base.ref
123123
run: echo "Lowest unmerged PR in the stack"
124124

125125
- name: Run for the top PR in the stack
126-
if: github.event.pull_request.stack.position == github.event.pull_request.stack.size
126+
if: github.event.pull_request.stack != null && github.event.pull_request.stack.position == github.event.pull_request.stack.size
127127
run: echo "Top PR in the stack"
128128
```
129129

0 commit comments

Comments
 (0)