diff --git a/src/content/docs/merge-queue/lifecycle.mdx b/src/content/docs/merge-queue/lifecycle.mdx
index 0ae12a92f6..441bdb42f2 100644
--- a/src/content/docs/merge-queue/lifecycle.mdx
+++ b/src/content/docs/merge-queue/lifecycle.mdx
@@ -120,13 +120,15 @@ the queue.
rules](/merge-queue/priority).
2. **Waiting for its turn:** The pull request waits in the queue until it is its
- turn to merge. Merges happen in queue order, one [batch](/merge-queue/batches)
- at a time, but the testing that precedes them does not:
- `merge_queue.max_parallel_checks` defaults to `5`, so Mergify tests up to five
- batches at once with [parallel
+ turn to merge. In the default [serial mode](/merge-queue/queue-modes), merges
+ happen in queue order, one [batch](/merge-queue/batches) at a time, but the
+ testing that precedes them does not: `merge_queue.max_parallel_checks`
+ defaults to `5`, so Mergify tests up to five batches at once with [parallel
checks](/merge-queue/performance#parallel-checks). At the default
`batch_size` of 1, that is five queued pull requests. Set
- `max_parallel_checks` to `1` to test them strictly one after the other.
+ `max_parallel_checks` to `1` to test them strictly one after the other. In
+ parallel and isolated modes, batches that do not depend on each other merge
+ as soon as their own checks pass, rather than in strict queue order.
3. **Validating the pull request:** When a pull request is next in line, it
enters the validation phase. During this phase, the Mergify engine will
@@ -372,10 +374,12 @@ deleted only when **both** of the following are true:
With the default prefix, a matching branch looks like
`mergify/merge-queue/a76b1f3d25`. With a custom `queue_branch_prefix` such as
-`mergify-`, it looks like `mergify-a76b1f3d25`. The temporary `tmp-` branch
-Mergify creates during setup (for example, `tmp-mergify/merge-queue/a76b1f3d25`)
-is matched the same way. A CI retry generates a fresh name of the same shape,
-with no extra suffix.
+`mergify-`, it looks like `mergify-a76b1f3d25`. A CI retry generates a fresh
+name of the same shape, with no extra suffix.
+
+Mergify no longer creates `tmp-` branches; a queue branch is pushed straight to
+its final name. The prefix is still matched so that branches left behind by
+older versions get cleaned up.
:::caution
Matching is by name only: Mergify does not track which branches it created.
@@ -397,8 +401,10 @@ them:
2. **Check the Mergify checks tab on the PR:** On each pull request page, the
- "checks" tab will show the status of the Mergify checks. If the pull request
- is in the queue, you will see a "Mergify — Queued" status.
+ "checks" tab will show the status of the Mergify checks. A queued pull
+ request has a "Mergify Merge Queue" check run whose title shows its state:
+ "In merge queue" while it waits its turn, "Running merge queue checks" while
+ its batch is being tested.
diff --git a/src/content/docs/merge-queue/merge-strategies.mdx b/src/content/docs/merge-queue/merge-strategies.mdx
index 448f0432df..fa84e94c27 100644
--- a/src/content/docs/merge-queue/merge-strategies.mdx
+++ b/src/content/docs/merge-queue/merge-strategies.mdx
@@ -21,7 +21,7 @@ shape, with trade-offs between linearity, SHA preservation, and throughput.
| `fast-forward` | Linear | Original commits moved to base | Yes | Serial only |
| `merge-batch` | Non-linear | Batch branch commits + 1 merge commit per batch | No | Full |
-## Merge (Default)
+## Merge
```yaml
queue_rules:
diff --git a/src/content/docs/merge-queue/stacks.mdx b/src/content/docs/merge-queue/stacks.mdx
index 64ec5d798b..1e351af445 100644
--- a/src/content/docs/merge-queue/stacks.mdx
+++ b/src/content/docs/merge-queue/stacks.mdx
@@ -84,6 +84,11 @@ chained only by branch refs (for example, GitFlow promotion chains like
`Depends-On:` marker, the queue keeps each PR's literal base ref and queues
them independently.
+A stack pushed with `--github-native` carries no `Depends-On:` marker either,
+because GitHub's stacking API holds the ordering instead. Those PRs are
+recognized as a [GitHub-native stack](#github-native-stacked-pull-requests) and
+land the way that section describes, one member at a time.
+
The last condition is why a stack cannot be opened from a fork. The first two
signals compare branch *names*, which only mean something inside one
repository: any fork can have a branch called `main`, so a fork PR's head
diff --git a/src/content/docs/stacks/concepts.mdx b/src/content/docs/stacks/concepts.mdx
index 3d1235dd0d..e9ae88a053 100644
--- a/src/content/docs/stacks/concepts.mdx
+++ b/src/content/docs/stacks/concepts.mdx
@@ -100,9 +100,12 @@ git config mergify-cli.stack-branch-prefix "my-prefix"
`--branch-prefix` overrides it for a single run. It is accepted by
`mergify stack push` and by the commands that read the stack back
-(`mergify stack checkout`, `mergify stack list`, `mergify stack open` and
-`mergify stack sync`), so a prefix passed on the command line has to be
-repeated on each of them. Set the Git config if you would rather not.
+(`mergify stack list`, `mergify stack open` and `mergify stack sync`), so a
+prefix passed on the command line has to be repeated on each of them. Set the
+Git config if you would rather not.
+
+`mergify stack checkout` takes no prefix: it resolves the stack from the
+branch name or PR URL you give it, no matter who pushed it.
## PR Chaining
@@ -131,6 +134,14 @@ branches in the repository the stack targets, the queue treats each PR
independently. `mergify stack push` satisfies all three, which is why a stack
is pushed to the repository itself rather than to a fork.
+A stack registered with GitHub's own stacking API by
+[`--github-native`](/stacks/setup#configuration) is the exception. GitHub holds
+the ordering there, so the descriptions carry no `Depends-On:` marker and the
+queue recognizes the PRs as a
+[GitHub-native stack](/merge-queue/stacks#github-native-stacked-pull-requests)
+instead. Every member can be queued, and they land one at a time from the
+bottom up rather than the chain moving as a unit.
+
## Smart Updates
When you push again after making changes, Stacks doesn't recreate everything. It
diff --git a/src/content/docs/stacks/setup.mdx b/src/content/docs/stacks/setup.mdx
index e32e5655ef..132d240c00 100644
--- a/src/content/docs/stacks/setup.mdx
+++ b/src/content/docs/stacks/setup.mdx
@@ -134,9 +134,9 @@ git config mergify-cli.stack-create-as-draft true
`--draft`, `--github-native`, `--keep-pull-request-title-and-body` and
`--no-revision-history`) to override the setting for a single push.
-`--branch-prefix` is also accepted by `mergify stack checkout`,
-`mergify stack list`, `mergify stack open` and `mergify stack sync`, which have
-to look for the same branches. Setting the Git config once covers all five.
+`--branch-prefix` is also accepted by `mergify stack list`,
+`mergify stack open` and `mergify stack sync`, which have to look for the same
+branches. Setting the Git config once covers all four.
:::note
`mergify-cli.stack-github-native` is experimental. On top of the usual push,
diff --git a/src/content/docs/stacks/team.mdx b/src/content/docs/stacks/team.mdx
index 822581e580..f1963e4dd9 100644
--- a/src/content/docs/stacks/team.mdx
+++ b/src/content/docs/stacks/team.mdx
@@ -44,17 +44,21 @@ As more developers see the benefits in review, adoption spreads naturally.
## Working on Someone Else's Stack
If a teammate has pushed a stack and you want to pick it up locally (to help,
-pair, or continue the work), use `checkout` with their stack name and their
-GitHub login:
+pair, or continue the work), point `checkout` at any PR in it:
```bash
-mergify stack checkout feat/their-feature --author their-login
+mergify stack checkout https://github.com/owner/repo/pull/142
```
-`--author` matters here: it defaults to the user your own token belongs to, so
-without it the command looks for a stack of yours under that name. Pass
-`--branch` to control the local branch name, which otherwise comes from the
-stack name.
+Any PR in the stack identifies the whole chain, so one from the middle works as
+well as the tip. The URL carries the repository, which means `--repository` is
+ignored when you check out this way. You can also name the stack's remote
+branch instead of passing a URL.
+
+The local branch is named after the stack's branch with your own
+[branch prefix](/stacks/setup#configuration) stripped off. The default prefix
+contains your username, so a teammate's stack isn't under it and the name falls
+back to the branch's last segment. Pass `--branch` to choose the name yourself.
This reconstructs the stack locally by fetching the remote branches and
rebuilding the commit chain. You can then make changes and push updates with