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