dsh-merging-stacked-prs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Landing an official GitHub PR stack

合并官方GitHub PR堆叠

Land dependent PRs through GitHub's native stack object and

gh stack merge

. Do not reproduce stack semantics by merging and retargeting individual PRs with

gh pr merge

and

gh pr edit

. The root AGENTS.md owns the allowed merge-forward and rebase histories; the stack review guide owns review-fix propagation.

通过GitHub原生堆叠对象和

gh stack merge

来合并依赖PR。请勿使用

gh pr merge

和

gh pr edit

逐个合并并重定向PR来模拟堆叠语义。根目录下的AGENTS.md规定了允许的向前合并和变基历史；堆叠审查指南规定了审查修复的传播规则。

Require native stack support

要求原生堆叠支持

Run

gh stack --version

before changing GitHub state. Hard-stop if the official extension or server-side stack feature is unavailable; do not fall back to manually merging and retargeting PRs one at a time. GitHub stacks require every head branch to live in the same repository, so hard-stop on a cross-fork chain.

Use a clean dedicated worktree. Fetch current PR metadata and exact head OIDs rather than trusting branch names or an earlier report:

gh pr view <pr> --json number,author,baseRefName,baseRefOid,headRefName,headRefOid,isCrossRepository,state,isDraft,reviewDecision,mergeStateStatus,statusCheckRollup

Query

PullRequest.stack

and

stackEntry.position

for at least one PR in each apparent chain; this official GitHub object, not base-branch inference alone, is the stack-membership authority. Paginate

entries

when

size

exceeds the returned page:

gh api graphql -F owner=<owner> -F name=<repo> -F number=<pr> -f query='
query($owner: String!, $name: String!, $number: Int!) {
  repository(owner: $owner, name: $name) {
    pullRequest(number: $number) {
      number
      author { login }
      baseRefName
      headRefName
      stackEntry { position }
      stack {
        number
        baseRefName
        size
        entries(first: 100) {
          nodes {
            position
            pullRequest { number author { login } baseRefName headRefName state isDraft }
          }
        }
      }
    }
  }
}'

Establish the expected bottom-to-top order from the live PR bases: the bottom targets the trunk, and each higher PR targets the head branch immediately below it.

在修改GitHub状态前运行

gh stack --version

检查版本。如果官方扩展或服务器端堆叠功能不可用，请立即停止操作；不要退回到手动逐个合并并重定向PR的方式。GitHub堆叠要求所有头分支都位于同一仓库中，因此跨仓库的依赖链需直接终止操作。

使用干净的专用工作区。拉取当前PR的元数据和精确的头OID，而非信任分支名称或早期报告：

gh pr view <pr> --json number,author,baseRefName,baseRefOid,headRefName,headRefOid,isCrossRepository,state,isDraft,reviewDecision,mergeStateStatus,statusCheckRollup

针对每个可见链中的至少一个PR，查询

PullRequest.stack

和

stackEntry.position

；这个GitHub官方对象是判定堆叠成员身份的权威依据，而非仅通过基础分支推断。当

size

超过返回页面时，对

entries

进行分页查询：

gh api graphql -F owner=<owner> -F name=<repo> -F number=<pr> -f query='
query($owner: String!, $name: String!, $number: Int!) {
  repository(owner: $owner, name: $name) {
    pullRequest(number: $number) {
      number
      author { login }
      baseRefName
      headRefName
      stackEntry { position }
      stack {
        number
        baseRefName
        size
        entries(first: 100) {
          nodes {
            position
            pullRequest { number author { login } baseRefName headRefName state isDraft }
          }
        }
      }
    }
  }
}'

根据实时PR的基础分支确定预期的从下到上顺序：最底层PR以主干为目标，每个上层PR以其正下方的头分支为目标。

Link missing stack members

关联缺失的堆叠成员

First compare any existing stack entries with the expected chain. One existing stack may contain an order-preserving subset of the requested chain; multiple stack numbers, an unexpected entry, or a conflicting order requires user direction before any mutation.

When any dependent PR is not yet in that official stack:

Compare every
```
author.login
```
exactly.
If all authors match, link the chain automatically in bottom-to-top order:

gh stack link --base <trunk> <bottom-pr> <next-pr> ... <top-pr>

If authors differ or any author is unavailable, ask the user whether to link before changing GitHub state.
Re-query GraphQL and require one stack number, the expected trunk, the complete PR set, and the expected positions and base chain.

Never dissolve, reorder, or rebuild an existing stack automatically;

gh stack link

is additive and merged or queued entries cannot be unstacked.

首先将现有堆叠条目与预期链进行对比。一个现有堆叠可能包含请求链中顺序保留的子集；若出现多个堆叠编号、意外条目或冲突顺序，需先获取用户指示再进行任何变更操作。

当任何依赖PR尚未加入该官方堆叠时：

精确比对每个
```
author.login
```
。
如果所有作者匹配，自动按从下到上的顺序关联整个链：

gh stack link --base <trunk> <bottom-pr> <next-pr> ... <top-pr>

如果作者不同或任何作者不可用，在修改GitHub状态前询问用户是否进行关联。
重新查询GraphQL，要求返回一个堆叠编号、预期的主干分支、完整的PR集合，以及预期的位置和基础链。

请勿自动解散、重新排序或重建现有堆叠；

gh stack link

是增量式操作，已合并或排队的条目无法从堆叠中移除。

Refresh only when needed

仅在必要时刷新

Do not rewrite branches merely because a refresh mechanism exists. When the live merge state or repository rules require an updated trunk, choose either allowed history:

Native cascading rebase: check out the remote stack with
```
gh stack checkout <pr-or-stack>
```
when it is not tracked locally, then run
```
gh stack sync
```
. The command may rebase and lease-protected force-push every active layer before local validation. Immediately inspect the rewritten scope, run the relevant checks for every affected layer, and do not merge or claim readiness until they pass. If sync detects a rebase conflict, use
```
gh stack rebase
```
, resolve and validate it, then publish with
```
gh stack push
```
. If checkout or sync reports divergent local and remote stack compositions, cancel and ask rather than deleting or recreating the remote stack automatically.
Incremental merge-forward: merge the trunk into the bottom affected branch, then propagate each updated parent into its child in bottom-to-top order and push normally. If the base advances during an in-progress merge, preserve that checkpoint before merging the newer tip as specified by the incremental-retargeting note.

Any history rewrite is allowed after review, but it invalidates commit-OID assumptions. Re-fetch exact heads and re-audit unresolved review threads, approvals, mergeability, and checks after the push. Never use raw

--force

or overwrite a concurrently advanced remote head.

不要仅仅因为存在刷新机制就重写分支。当实时合并状态或仓库规则需要更新主干时，选择以下两种允许的历史处理方式之一：

原生级联变基：当远程堆叠未在本地跟踪时，使用
```
gh stack checkout <pr-or-stack>
```
检出远程堆叠，然后运行
```
gh stack sync
```
。该命令可能会对每个活跃层进行变基并通过租赁保护进行强制推送，之后再进行本地验证。立即检查重写的范围，对每个受影响的层运行相关检查，在检查通过前不要合并或声明已准备就绪。如果同步检测到变基冲突，使用
```
gh stack rebase
```
解决冲突并验证，然后通过
```
gh stack push
```
发布。如果检出或同步报告本地与远程堆叠结构存在分歧，请取消操作并询问用户，而非自动删除或重建远程堆叠。
增量向前合并：将主干合并到最底层的受影响分支，然后按从下到上的顺序将每个更新后的父分支传播到其子分支，并正常推送。如果在合并进行过程中基础分支推进，请按照增量重定向说明中的规定，在合并新版本的尖端前保留该检查点。

任何历史重写需在审查后进行，但会使提交OID的假设失效。推送后需重新拉取精确的头分支，并重新审核未解决的审查线程、批准状态、可合并性和检查结果。请勿使用原生

--force

参数或覆盖同时推进的远程头分支。

Preflight the merge range

预检查合并范围

Re-query the official stack immediately before merging. Require every selected PR to be open, non-draft, in the expected order, and compliant with the repository's review and check requirements. Treat each PR's state independently; a ready top layer does not prove its dependencies are ready.

"Land the stack" selects the whole stack. A partial landing requires an explicit boundary PR and includes every layer from the bottom through that boundary.

在合并前立即重新查询官方堆叠。要求每个选中的PR处于开放状态、非草稿、符合预期顺序，并且满足仓库的审查和检查要求。独立处理每个PR的状态；顶层PR已准备就绪并不代表其依赖项也已准备就绪。

「合并堆叠」会选择整个堆叠。部分合并需要明确指定边界PR，并包含从最底层到该边界的所有层。

Merge through the stack API

通过堆叠API合并

Merge the whole stack by its official stack number:

gh stack merge <stack-number> --yes --merge

For an explicitly requested partial landing, merge through the boundary PR:

gh stack merge <boundary-pr> --yes --merge

Do not pass

--delete-branch

, manually retarget dependents, or issue per-PR merge commands. GitHub merges the selected range bottom-up and retargets/rebases any remaining upper layers. A direct stack merge is all-or-nothing; when the trunk uses a merge queue, GitHub queues the selected range together but may land it in separate groups.

Do not bypass merge requirements. If the native merge reports a blocker, inspect and resolve that blocker through the owning PR or stop and report it; never fall back to

gh pr merge

通过官方堆叠编号合并整个堆叠：

gh stack merge <stack-number> --yes --merge

对于明确要求的部分合并，通过边界PR进行合并：

gh stack merge <boundary-pr> --yes --merge

请勿传递

--delete-branch

参数、手动重定向依赖项或发出针对单个PR的合并命令。GitHub会自下而上合并选中的范围，并对剩余的上层PR进行重定向/变基。直接堆叠合并是全有或全无的操作；当主干使用合并队列时，GitHub会将选中的范围一起加入队列，但可能会分组合并。

请勿绕过合并要求。如果原生合并报告存在阻塞问题，请通过对应的PR检查并解决该问题，或停止操作并报告；切勿退回到使用

gh pr merge

。

Verify the landed state

验证合并后的状态

Wait for every selected PR to report

MERGED

; a queued request is not a completed landing:

gh pr view <pr> --json number,state,mergedAt,mergeCommit,baseRefName,headRefName

For a partial landing, re-query the official stack and verify that every remaining PR is still linked in the expected order and targets the stack trunk or the layer below it. Re-check current heads, review state, and CI because GitHub may have rebased the remaining layers.

Delete branches only in a separate final pass after the corresponding PRs report

MERGED

. Before deleting each branch, require GitHub to report no open PR still using it as a base:

gh pr list --state open --base <branch> --json number --jq length

Anything other than

blocks deletion.

等待每个选中的PR报告

MERGED

状态；排队请求并不代表合并已完成：

gh pr view <pr> --json number,state,mergedAt,mergeCommit,baseRefName,headRefName

对于部分合并，重新查询官方堆叠并验证所有剩余PR仍按预期顺序关联，且以堆叠主干或其下方的层为目标。重新检查当前头分支、审查状态和CI，因为GitHub可能已对剩余层进行了变基。

仅在对应的PR报告

MERGED

状态后，再单独进行分支删除操作。在删除每个分支前，要求GitHub报告没有开放PR仍将其作为基础分支：

gh pr list --state open --base <branch> --json number --jq length

结果不为

则阻止删除操作。

Checklist

检查清单

Native
```
gh stack
```
support is available; every PR branch is in the same repository.
Live PR bases and exact heads establish one bottom-to-top dependency chain.
GraphQL reports one official stack with the expected trunk, entries, and order; an eligible same-author unstacked chain was linked automatically.
Any rewritten layers passed relevant validation, and review threads, approvals, mergeability, and checks were re-audited afterward.
The whole stack, or an explicitly bounded prefix, was submitted through
```
gh stack merge --yes --merge
```
.
Every selected PR reports
```
MERGED
```
; any remaining upper layers still form the expected official stack.
Branch deletion happened only after merged-state and zero-dependent verification.

原生
```
gh stack
```
功能可用；所有PR分支都位于同一仓库中。
实时PR的基础分支和精确头分支构成一条从下到上的依赖链。
GraphQL返回一个包含预期主干、条目和顺序的官方堆叠；符合条件的同一作者未堆叠链已自动关联。
所有重写的层都通过了相关验证，并且在推送后重新审核了审查线程、批准状态、可合并性和检查结果。
整个堆叠或明确限定的前缀已通过
```
gh stack merge --yes --merge
```
提交。
每个选中的PR都报告
```
MERGED
```
状态；所有剩余的上层PR仍构成预期的官方堆叠。
分支删除仅在验证合并状态和无依赖PR后进行。