Skip to content

docs: Explain native GitHub stacks #1406

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
abhinav wants to merge 1 commit into from
Draft

docs: Explain native GitHub stacks #1406

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .changes/unreleased/Added-20260805-045615.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
kind: Added
body: 'submit: Eligible GitHub pull requests are registered as native stacks after submission.'
body: >-
submit: Eligible GitHub pull requests are registered as native stacks after submission,
including membership, order, and base changes on later submissions.
time: 2026-08-05T04:56:15.840512-07:00
30 changes: 30 additions & 0 deletions doc/src/guide/cr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,36 @@ configuration key.
However, it is unable to do this following complex stack manipulation
operations.

### GitHub native stacks

<!-- gs:version unreleased -->

After a successful submission,
git-spice registers eligible pull requests in the affected stack
with GitHub's native stacked pull request support.
GitHub native stacks must be linear
and all head branches must belong to the repository receiving the pull requests.
For a divergent local stack,
git-spice preserves an existing compatible native stack path.
Otherwise, git-spice registers one longest path
and warns about each omitted path.

On later submissions,
git-spice reconciles the selected path with its existing GitHub native stack.
This includes inserting, removing, or reordering pull requests.
When the composition changes,
git-spice dissolves the old native stack before changing pull request bases,
then recreates the desired stack.
If a pull request is queued or has auto-merge enabled,
GitHub may prevent restructuring;
git-spice leaves that native stack unchanged and warns.

Native stack metadata is supplemental.
If GitHub does not support native stacks,
submission continues without them.
Other native stack update failures produce a warning
but do not fail an otherwise successful submission.

### Non-interactive submission

Use the `--fill` flag (or `-c` since <!-- gs:version v0.3.0 -->)
Expand Down
19 changes: 19 additions & 0 deletions doc/src/guide/merge.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -296,6 +296,25 @@ text "feat5" color red
{gray}# merges all branches into main{reset}
```

### Native stack merges

<!-- gs:version unreleased -->

When the forge supports atomic stack merges,
git-spice merges each eligible linear range as one operation.
Every branch in the range must be fully restacked,
and its remote base, head branch, and head commit must match
before git-spice requests the merge.
If the forge does not support the range operation,
git-spice falls back to the usual bottom-up merge sequence.

A divergent selection is split at each fork.
The shared linear range is merged first,
then each divergent path continues independently after repository sync.
If an unselected branch diverges from a merged GitHub native stack,
git-spice also runs repository sync after the range merge
to retarget the surviving branch and its pull request.

## Custom merge processes

git-spice uses the Forge's merge APIs to merge CRs.
Expand Down
Loading