ship-it

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ship it: commit, open the PR, get CI green

交付代码：提交、打开PR、确保CI检查通过

Finish with the change committed, pushed, open as a ready pull request, and green in CI. Invoking

$ship-it

authorizes that complete workflow. Pause only for a material ambiguity, a required approval, or a failure that cannot be resolved with the available access.

Work on a feature branch, never the default branch (in a worktree if that is the repo's flow). If you are already on a feature branch, stay on it. Follow the repo's branch-naming convention. When the repo has none and a branch is needed, use the

agent/

prefix.

最终要实现代码变更已提交、推送、作为就绪状态的PR打开，且CI检查全部通过。调用

$ship-it

即授权执行完整工作流。仅在存在重大歧义、需要审批，或者无法用现有权限解决故障时才暂停。

在功能分支上开展工作，绝对不要直接操作默认分支（如果仓库采用工作树流程，则在工作树中进行）。若已处于功能分支，则继续使用该分支。遵循仓库的分支命名规范。如果仓库没有相关规范且需要创建分支，使用

agent/

前缀。

1. Verify locally before you commit

1. 提交前先在本地验证

Never push work you have not proven builds and passes. Run the repo's own checks, cheapest first. Find them in the contributor docs or the CI config; do not assume a toolchain.

Generate first if the repo has a codegen step. If some code is generated (and may be gitignored or must be refreshed after a source edit), run that step before building; skipping it produces confusing "undefined symbol" build errors that are not real.
Mirror what CI runs. Read the CI config (or the contributor docs) to see the real checks, then run them locally so CI is not the first place you see a failure: the repo's formatter, its linter, its pre-commit checks, its build, and the tests for what you touched.
Know your local gaps. Some checks cannot run on your machine (a tool or platform CI has that you do not). Run what you can, note the gap, and let CI cover it rather than treating a local-environment limitation as a real failure.
Run the full or integration suite when the change reaches it. Include tests that need services or extra setup: those often skip silently when unconfigured, so a green run can be hollow. Make sure the relevant ones actually ran. A change that does not reach that layer may not need it.

When a fix breaks a test, do not just patch the one failure: scan for other call sites or fixtures that relied on the old behavior, so the next CI run does not surface a sibling break.

绝对不要推送未经验证可构建且通过检查的代码。先运行仓库自带的检查，优先执行成本最低的检查。可在贡献者文档或CI配置中找到这些检查项，不要假设工具链的情况。

**如果仓库有代码生成步骤，先执行生成操作。**若部分代码是自动生成的（可能被git忽略，或在修改源码后需要刷新），请在构建前运行生成步骤；跳过此步骤会产生令人困惑的“未定义符号”构建错误，而这些错误并非真实存在的问题。
**复刻CI执行的检查内容。**查看CI配置（或贡献者文档）了解实际执行的检查项，然后在本地运行这些检查，避免CI成为第一个发现故障的地方：包括仓库的格式化工具、代码检查工具、提交前检查、构建流程，以及你所修改代码对应的测试。
**了解本地环境的局限性。**部分检查无法在你的机器上运行（CI拥有的某些工具或平台你没有）。尽可能运行可执行的检查，记录局限性，由CI来覆盖这些无法本地运行的检查，不要将本地环境的限制视为真实故障。
**当变更涉及到完整或集成测试套件时，运行对应测试。**包括需要服务或额外配置的测试：这些测试在未配置时通常会静默跳过，因此看似通过的运行可能是无效的。确保相关测试确实已执行。若变更未涉及到该层级，则无需运行。

当修复导致测试失败时，不要只修补单个故障：扫描所有依赖旧行为的调用点或测试夹具，避免下一次CI运行出现其他相关故障。

2. Commit

2. 提交代码

Inspect the complete diff and the working tree before staging. Preserve unrelated user changes. Group related files into logical commits and stage explicit paths. Write each message with a clean body:

git add <paths>
git commit -m "$(cat <<'EOF'
<Imperative subject line, no trailing period>

<Body: explain WHY the change is needed and what it does, not a restatement of
the diff. Wrap at ~80 columns.>

<attribution trailer required by the active global instructions, if any>
EOF
)"

Rules that always hold:

Imperative subject ("Fix the stale cache read...", "Reject empty payloads...").
The body carries the reasoning. Bump any shared version or sequence constants the change requires and say so.
Apply the standing attribution, punctuation, and
```
stop-slop
```
rules to the message and the PR body.

在暂存前检查完整的差异和工作树。保留无关的用户变更。将相关文件分组为逻辑提交，并暂存明确的路径。为每个提交编写清晰的正文：

git add <paths>
git commit -m "$(cat <<'EOF'
<祈使语气的主题行，末尾不要加句号>

<正文：说明变更的必要性和作用，不要重复差异内容。每行约80个字符换行。>

<若当前全局规则要求，添加归属信息尾注>
EOF
)"

始终遵循以下规则：

主题行使用祈使语气（例如“修复缓存读取过期问题...”、“拒绝空负载...”）。
正文阐述变更原因。若变更需要更新共享版本或序列常量，请进行更新并在正文中说明。
提交信息和PR正文需遵循现有的归属、标点和
```
stop-slop
```
规则。

3. Open the PR

3. 打开PR

Push the branch and check whether it already has an open PR:

gh pr list --state open --head <branch> --json number,title,url,isDraft,baseRefName,headRefName

Reuse the existing PR when present. Update its title and body, correct its base if needed, and mark it ready with

gh pr ready <n>

when it is a draft. Otherwise, create a ready PR with a self-contained body:

gh pr create --base <default-branch> --head <branch> \
  --title "<same imperative style as the commit subject>" \
  --body "$(cat <<'EOF'

推送分支并检查是否已有对应的开放PR：

gh pr list --state open --head <branch> --json number,title,url,isDraft,baseRefName,headRefName

若已有PR则复用该PR。更新其标题和正文，必要时修正基准分支，当PR为草稿状态时使用

gh pr ready <n>

标记为就绪。否则，创建一个就绪状态的PR，正文需完整独立：

gh pr create --base <default-branch> --head <branch> \
  --title "<与提交主题相同的祈使语气风格>" \
  --body "$(cat <<'EOF'

Why this change

变更原因

Fixes #<issue>.

Fixes #<issue编号>。

<当前存在的问题及其影响。>

What changed

变更内容

<变更的具体作用，以简短的项目符号列表呈现。>

Testing

测试情况

<attribution footer required by the active global instructions, if any> EOF )"


Notes:

- Reference the issue with `Fixes #<n>` (or `Closes #<n>`) when the work started
  from one; many workstreams open with "plan and implement a fix for issue N".
- Flex headings to fit the change while keeping the reason, implementation, and
  concrete verification easy to find. Include configuration instructions only
  when setup or runtime configuration changed. A short fenced code block for a
  key type or signature is useful when it clarifies the change.
- Add an attribution footer only when the active global instructions require it.
- Base the default branch. Create a normal ready PR, with no labels or reviewers
  unless asked. Do not add an agent-specific title prefix.
- Before watching CI, verify the final PR's base, head, readiness, title, body,
  and URL with `gh pr view`.

<执行的具体命令及其结果。若未运行某项检查，请说明原因。>

<若当前全局规则要求，添加归属信息页脚> EOF )"


注意事项：

- 若工作始于某个issue，使用`Fixes #<n>`（或`Closes #<n>`）关联该issue；许多工作流以“规划并修复issue N”为开端。
- 根据变更调整标题，同时确保变更原因、实现方式和具体验证内容易于查找。仅当设置或运行时配置发生变更时，才添加配置说明。关键类型或签名的简短代码块有助于明确变更内容。
- 仅当当前全局规则要求时，才添加归属信息页脚。
- 以默认分支为基准分支。创建常规的就绪状态PR，除非另有要求，否则不要添加标签或指定审核人。不要添加Agent专属的标题前缀。
- 在监控CI之前，使用`gh pr view`验证最终PR的基准分支、头部分支、就绪状态、标题、正文和URL。

4. Get CI green

4. 确保CI检查全部通过

CI is not green until every check passes: the build (across whatever matrix it runs), the test job, and the formatter and linter checks.

Wait with

gh pr checks <n> --watch --interval 20

(it blocks until the run resolves), in the foreground or as a background job. Watch the complete check set so a filtered view cannot hide a failure. When a check fails, start with the complete failed-job log, then search within it as needed:

gh run view <run-id> --log-failed

Then loop: diagnose the failure, fix it, re-run the local gates from step 1, commit the fix, push, and re-poll. A first red run is normal and useful (it catches hidden dependencies like a fixture that relied on old behavior); keep going until it is all green. Do not declare done on a partial pass.

只有当所有检查项都通过时，CI才处于“绿色”状态：包括构建（无论其运行的矩阵如何）、测试任务，以及格式化和代码检查。

使用

gh pr checks <n> --watch --interval 20

等待检查结果（该命令会阻塞直至运行结束），可在前台或后台运行。监控完整的检查集，避免筛选视图隐藏故障。当检查失败时，先查看完整的失败任务日志，再根据需要在日志内搜索：

gh run view <run-id> --log-failed

然后循环执行以下步骤：**诊断故障、修复问题、重新运行步骤1中的本地检查、提交修复、推送、重新轮询检查状态。**首次运行失败是正常且有帮助的（它能发现隐藏的依赖，例如依赖旧行为的测试夹具）；持续执行直至所有检查通过。不要在部分通过时就宣告完成。

5. Report

5. 汇报工作

Close with the PR link and the concrete green state: which check groups passed, what shipped as a short list of commits, and any first-run failure fixed along the way. State plainly that CI is fully green.

以PR链接和明确的“绿色”状态结束汇报：说明哪些检查组已通过，交付的代码包含哪些简短的提交列表，以及修复的首次运行故障。明确说明CI已全部通过。