ship
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseShip
交付上线
Objective
目标
Carry intentional code changes to the endpoint the user asks for, and no further:
- Open: create the PRs and leave them open.
- Watch: open or continue PRs, then address checks and reviews during the session; the PRs stay open.
- Ship / land: merge and verify the result.
Do the prerequisite branching, committing, and corrective pushes within that scope. Never report an outcome you have not verified.
将有意图的代码更改交付到用户要求的终点,且不超出该范围:
- Open(发起): 创建 PR,并保持其处于开放状态。
- Watch(观察): 发起或继续处理 PR,然后在本次会话期间处理 checks 和 reviews;PR 保持开放。
- Ship / land(交付 / 落地): 合并并验证结果。
在该范围内完成必要的分支创建、提交和修正性推送。绝不报告尚未验证的结果。
1. Inspect and partition
1. 检查与划分
Read the repository's instructions. Inspect the current and base branches, the remote, existing PRs, the full diff, staged and unstaged changes, and untracked files. Before staging, check for credentials, generated files, and other unintended content.
base...HEADInclude all intentional work unless the user named a subset. Preserve unrelated or uncertain changes, and ask about ownership only when the answer changes what can safely ship.
Group changes into units of behavior, not files. Keep a unit's code, tests, and docs together even across files; separate unrelated behavior even within one file, using selective hunk staging. Each commit should be reviewable and valid in the order it will land.
Choose the smallest PR graph that keeps boundaries honest:
- One PR for related commits that share a purpose and can be reviewed and reverted together.
- Independent PRs from the same base for changes that build and test without each other.
- Stacked PRs only when one change needs another to compile, test, or make sense. Put foundations below consumers; each PR shows only its own layer against its parent.
Don't split a single dependent change just to make more PRs. If an apparently independent change turns out to rely on another, revise the graph rather than publish a misleading diff. Continue an existing PR instead of duplicating it. Share the proposed grouping in a brief progress update and proceed once the boundaries are clear.
读取仓库的说明。检查当前分支和 base 分支、远程仓库、现有 PR、完整的 diff、已暂存和未暂存的更改,以及未跟踪文件。在暂存前,检查凭据、生成文件和其他非预期内容。
base...HEAD除非用户明确指定了某个子集,否则应纳入所有有意完成的工作。保留无关或归属不明的更改;仅当归属答案会影响哪些内容可以安全交付时,才询问相关归属。
按行为单元而非文件对更改进行分组。即使跨越多个文件,也应将一个单元的代码、测试和文档放在一起;即使在同一文件中,也要将无关行为分开,并使用按 hunk 选择性暂存。每次提交都应便于审查,并且按照其实际落地顺序有效。
选择能够如实保持变更边界的最小 PR 图谱:
- 对于目标一致、可一起审查和回滚的相关提交,使用一个 PR。
- 对于无需依赖彼此即可构建和测试的更改,从同一 base 创建独立 PR。
- 仅当某项更改需要另一项更改才能编译、测试或合理成立时,才使用堆叠 PR。将基础层放在使用层下方;每个 PR 只展示相对于其父 PR 的自身层级。
不要仅仅为了创建更多 PR 而拆分单个存在依赖关系的更改。如果表面独立的更改最终被证明依赖另一项更改,应调整 PR 图谱,而不是发布具有误导性的 diff。应继续处理现有 PR,而不是创建重复 PR。在简短的进度更新中说明建议的分组,边界明确后继续执行。
2. Prepare commits and branches
2. 准备提交和分支
Run relevant local checks for each unit, and for the integrated result where units depend on each other.
Create branches from the intended base, and child branches from their parent in a stack. When the working tree holds several groups, isolate them with a temporary index, staging branch, or worktrees. Record any pre-existing staged changes and keep their grouping; avoid indiscriminate . A new branch name does not shed unrelated commits inherited from the current branch, so check ancestry.
git add -ABefore pushing, inspect every staged diff, every commit, and each PR's eventual diff, and confirm that local changes outside the task are still intact.
base...headPush only branches this task owns. No destructive resets, ordinary force pushes, or direct pushes to the base branch. If a lower-layer fix must be propagated through a published stack, confirm ownership and remote state, then use the repository's stack tooling or on the affected task branches only. Stop if anyone else's work could be overwritten, and rerun affected checks after the rewrite.
--force-with-lease为每个行为单元运行相关的本地 checks;对于存在依赖关系的单元,还要对集成后的结果运行检查。
从预期的 base 创建分支,并在堆叠中从父分支创建子分支。当工作区包含多个组别时,使用临时 index、staging branch 或 worktree 将它们隔离。记录预先存在的已暂存更改并保留其分组;避免不加区分地使用 。新分支名称不会自动移除从当前分支继承的无关提交,因此需要检查祖先关系。
git add -A推送前,检查每一个已暂存 diff、每一次提交,以及每个 PR 最终对应的 diff,并确认任务范围之外的本地更改仍然完好。
base...head仅推送本任务拥有的分支。不得执行破坏性 reset、普通 force push,或直接推送到 base 分支。如果必须将下层修复传播到已发布的 stack,应先确认所有权和远程状态,然后仅在受影响的任务分支上使用仓库的 stack 工具或 。如果可能覆盖他人的工作,应停止操作;重写后应重新运行受影响的 checks。
--force-with-lease3. Open the PRs
3. 发起 PR
Open independent PRs against the intended base. Open a stack bottom-up, each child targeting the branch directly below it; use GitHub's stack features when available, or ordinary PRs with explicit parent bases. Confirm each diff contains only its intended unit before publishing. Use a concise title that describes the outcome.
Write the shortest description that tells a reviewer what changed, why, and how it was checked. A small PR needs a short paragraph and a verification line:
markdown
Fix the reminder using the previous day's date after midnight. The date now comes from the user's timezone.
Verification: The midnight-boundary test and relevant checks pass.For larger changes, use and when headings help readers scan. Add design decisions, before/after evidence, screenshots, rollout steps, or risks only when they affect review or merging. Name relevant checks that could not run. For a stack, link the parent PR, state the review base and merge order, and update links once the stack exists. No boilerplate sections, and no results you did not observe.
## Summary## Verification针对预期的 base 发起独立 PR。发起 stack 时应自底向上进行,每个子 PR 都以紧邻其下层的分支为目标;可用时使用 GitHub 的 stack 功能,否则使用明确指定父级 base 的普通 PR。发布前,确认每个 diff 只包含其目标行为单元。使用简洁的标题描述结果。
编写能够以最短篇幅告诉审查者改了什么、为什么改动以及如何验证的描述。较小的 PR 只需一个简短段落和一行验证信息:
markdown
修复提醒功能,使其在午夜后使用前一天的日期。现在日期取自用户所在时区。
验证:午夜边界测试及相关检查均通过。对于较大的更改,当标题有助于读者快速浏览时,使用 和 。仅当设计决策、变更前后证据、截图、发布步骤或风险会影响审查或合并时,才添加这些内容。明确列出无法运行的相关 checks。对于 stack,应链接父 PR,说明审查 base 和合并顺序,并在 stack 建立后更新链接。不添加模板化板块,也不填写未实际观察到的结果。
## 摘要## 验证4. Watch and repair
4. 观察与修复
Monitor PRs in scope during the session, normally polling every 30–60 seconds. Read live PR state, checks and failed-job logs, published reviews and comments, and all unresolved review threads, paginating as needed. Handle feedback already present on the first pass; ignore unpublished reviews. A pass on an old SHA does not validate a new push or a changed base.
- Feedback: Verify it against the current code. Fix valid issues in the unit that owns them, run focused checks, commit, push, and recheck that PR and any descendants. Resolve your own or automated threads only after verifying the fix; leave other people's threads to them unless the user authorized resolving them. Surface requests that need a human answer or renewed approval.
- Failed checks: Diagnose before changing code. Fix branch-caused failures at their source. Retry likely transient failures up to three times; stop with a precise blocker when a failure recurs with no new diagnosis or an external service is down.
- Moving bases and stacks: When the base moves or a lower layer changes, is rebased, or is retargeted, recheck every affected diff, check, and review state. Each remaining child must still contain only its own change. Use the repository's stack workflow if it has one; otherwise update dependents carefully and verify their PR bases.
Keep watching pending checks and required or explicitly requested reviews until the requested endpoint is reached or a blocker remains. If no checks appear, give expected workflows time to register and inspect repository settings before concluding none apply. Don't invent an optional reviewer as a merge gate.
在本次会话期间监控范围内的 PR,通常每 30–60 秒轮询一次。读取实时 PR 状态、checks 和失败任务日志、已发布的 reviews 和评论,以及所有未解决的 review 线程,并在需要时分页。首次检查时即处理已经存在的反馈;忽略尚未发布的 reviews。旧 SHA 上的一次通过不能验证新的 push 或变更后的 base。
- 反馈: 根据当前代码验证反馈。负责该问题的行为单元中修复有效问题,运行针对性 checks,提交并推送,然后重新检查该 PR 及其所有后续 PR。只有在验证修复后,才能解决自己或自动化流程创建的线程;除非用户授权处理他人的线程,否则应留给其作者解决。明确提出需要人工答复或重新批准的事项。
- 失败的 checks: 修改代码前先进行诊断。由分支引起的失败应从根源修复。对于可能是暂时性问题的失败,最多重试三次;如果在没有新诊断的情况下再次失败,或外部服务不可用,应停止并给出明确的阻塞项。
- Base 移动与 stack 调整: 当 base 移动,或者下层发生更改、被 rebase 或被重定向时,重新检查所有受影响的 diff、checks 和 review 状态。剩余的每个子 PR 都必须仍然只包含自身的更改。如果仓库提供 stack 工作流,应优先使用;否则应谨慎更新依赖项并验证其 PR base。
持续等待尚未完成的 checks,以及必需或明确要求的 reviews,直到达到请求的终点或出现阻塞项。如果未出现 checks,应给预期工作流足够时间完成注册,并检查仓库设置,然后再判断是否没有适用的检查。不要虚构可选 reviewer 并将其作为合并门禁。
5. Merge and sync
5. 合并与同步
Merge only when merging is in scope. Merge independent PRs once their gates pass, and stacks from the bottom up. A stack tool may land several layers together only if every included PR is ready.
Immediately before each merge, freshly confirm the latest head, passing checks for that revision, valid required approvals, no actionable feedback or unresolved blocking threads, and mergeability. Honor branch protections and the repository's merge strategy. Never self-approve or use an admin bypass. If a person must approve or a permission blocks progress, keep watching while the session can run, or report the blocker.
After each merge, verify the PR's merged state and the resulting commit on the intended base. In a stack, recheck the next child's base, diff, checks, and approvals before continuing.
Then sync local state: fetch, fast-forward local target branches, update dependent local branches and worktrees, and move off a merged task branch onto the updated base. Delete owned merged branches once they're no longer needed. Preserve unrelated staged and unstaged changes; if a branch can't be updated safely, leave it intact and report the pending sync.
仅在合并属于任务范围时执行合并。独立 PR 在其门禁通过后即可合并;stack 则自底向上合并。只有当 stack 中包含的每个 PR 都已就绪时,stack 工具才能一次落地多个层级。
每次合并前,立即重新确认最新 head、该修订版本上通过的 checks、有效的必需 approvals、无待处理反馈或未解决的阻塞线程,以及可合并性。遵守分支保护规则和仓库的合并策略。绝不自我 approve,也绝不使用管理员绕过。如果必须由人工批准,或权限阻碍进度,应在本次会话仍可运行时继续监控,否则报告阻塞项。
每次合并后,验证 PR 的已合并状态,以及预期 base 上生成的 commit。对于 stack,继续处理前重新检查下一个子 PR 的 base、diff、checks 和 approvals。
随后同步本地状态:执行 fetch,快进本地目标分支,更新依赖的本地分支和 worktree,并从已合并的任务分支切换到更新后的 base。不再需要时,删除本任务拥有且已合并的分支。保留无关的已暂存和未暂存更改;如果某个分支无法安全更新,则保持其原状并报告待同步事项。
6. Report
6. 报告
Lead with the verified outcome and link the PRs. Match length to what the user needs: a clean merge may take one sentence, while several PRs in different states may warrant compact bullets or a table. Mention checks, caveats, or remaining work only when they affect the outcome, and don't restate the PR description.
For example:
Merged [#42: Fix reminder timezone](PR URL). Tests and CI passed.If the endpoint leaves PRs open, report observed checks and feedback, any pending next action, and that monitoring ends with this session. If blocked, link the open PRs, name the exact gate and next action, and identify intentional local changes left untouched. Never report a PR as merged until its merged state is verified.
首先给出已验证的结果和 PR 链接。根据用户的实际需要控制篇幅:顺利合并可能只需一句话,而多个处于不同状态的 PR 则适合使用紧凑的项目符号或表格。仅当 checks、注意事项或剩余工作会影响结果时才提及它们,不要复述 PR 描述。
例如:
已合并 [#42:修复提醒时区](PR URL)。测试和 CI 均已通过。如果终点要求保持 PR 开放,应报告已观察到的 checks 和反馈、任何待执行的下一步,并说明监控将随本次会话结束而停止。如果受到阻塞,应链接仍开放的 PR,指明具体的门禁和下一步操作,并说明哪些有意完成的本地更改保持未动。在验证 PR 的已合并状态之前,绝不能将其报告为已合并。
Principle
原则
Treat a failed check or review comment as evidence about intended behavior, not a reason to accumulate exceptions. Make the smallest coherent correction, keep commit and PR boundaries intact, and recheck every affected layer.
将失败的 check 或 review 评论视为有关预期行为的证据,而不是不断累积例外的理由。做出最小且连贯的修正,保持 commit 和 PR 边界完整,并重新检查每个受影响的层级。