merge queue: checking #12609 on main (6b00195), stacked on #12633

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:
 <Image src={queueStatusScreenshot} alt="Mergify queue status" />
 
 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.
 
 <Image src={queueCheckScreenshot} alt="Mergify check status" />
 

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:

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

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

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,

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