diff --git a/.changes/unreleased/Added-20260805-045615.yaml b/.changes/unreleased/Added-20260805-045615.yaml index 7d6c15963..d79188448 100644 --- a/.changes/unreleased/Added-20260805-045615.yaml +++ b/.changes/unreleased/Added-20260805-045615.yaml @@ -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 diff --git a/doc/src/guide/cr.md b/doc/src/guide/cr.md index 8412e8883..5b9bab936 100644 --- a/doc/src/guide/cr.md +++ b/doc/src/guide/cr.md @@ -147,6 +147,36 @@ configuration key. However, it is unable to do this following complex stack manipulation operations. +### GitHub native stacks + + + +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 ) diff --git a/doc/src/guide/merge.md b/doc/src/guide/merge.md index d3e206437..203f6ed08 100644 --- a/doc/src/guide/merge.md +++ b/doc/src/guide/merge.md @@ -296,6 +296,25 @@ text "feat5" color red {gray}# merges all branches into main{reset} ``` +### Native stack merges + + + +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.