ship-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ship Workflow

发布工作流（Ship Workflow）

Automated release pipeline that takes a feature branch from working state to merged PR. Executes a deterministic sequence of pre-flight checks, testing, review, versioning, and PR creation — stopping immediately on any failure with specific remediation instructions.

自动化发布流水线，可将特性分支从可用状态推进到PR合并阶段。它会按确定的顺序执行前置检查、测试、评审、版本更新和PR创建步骤，任何步骤失败都会立即终止，并给出明确的修复指导。

Pipeline Overview

流水线概览

pre-flight → merge main → test → review → version bump → changelog → bisectable commits → push → PR

Each step has explicit stop conditions. The pipeline never auto-resolves ambiguity.

pre-flight → merge main → test → review → version bump → changelog → bisectable commits → push → PR

每个步骤都有明确的终止条件，流水线永远不会自动解决歧义问题。

Step 1: Pre-flight Checks

步骤1：前置检查

Run all three checks before proceeding:

Not on default branch — detect the default branch dynamically:
bash
```
git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'
```
If the current branch matches: STOP. Instruct the user to create a feature branch.
Clean working tree —
```
git status --porcelain
```
must produce no output. If dirty: STOP. List the uncommitted files and instruct the user to commit or stash.
Up-to-date with remote —
```
git fetch origin
```
then compare local HEAD with
```
origin/<current-branch>
```
. If the remote is ahead: STOP. Instruct the user to pull or rebase.

If any check fails, STOP with the specific remediation instruction. Do not proceed.

继续操作前请先完成以下三项检查：

不在默认分支上 — 动态检测默认分支：
bash
```
git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'
```
如果当前分支与默认分支匹配：终止流程，提示用户创建特性分支。
工作树干净 —
```
git status --porcelain
```
必须无输出。如果工作树有未提交内容：终止流程，列出未提交文件，提示用户提交或暂存内容。
与远程分支同步 — 执行
```
git fetch origin
```
后对比本地HEAD与
```
origin/<当前分支>
```
，如果远程分支更新：终止流程，提示用户拉取或变基代码。

如果任意检查失败，都要终止流程并给出明确的修复指导，不要继续执行后续步骤。

Step 2: Merge Default Branch

步骤2：合并默认分支

bash

git fetch origin
git merge origin/<default-branch>

If merge conflicts occur: STOP. Report the conflicting files. Do not auto-resolve.
If clean: proceed.

bash

git fetch origin
git merge origin/<default-branch>

如果出现合并冲突：终止流程，上报冲突文件，不要自动解决冲突。
如果合并无冲突：继续后续步骤。

Step 3: Run Tests

步骤3：运行测试

Detect the test command from project configuration using

references/project-detection.md

Indicator	Test Command
`Makefile` with `test` target	`make test`
`package.json` with `test` script	`<detected-pkg-manager> run test`
`pyproject.toml` with pytest config	`uv run pytest` (or detected runner)
`Cargo.toml`	`cargo test`
`go.mod`	`go test ./...`
`Gemfile` + `Rakefile`	`bundle exec rake test`

Detection order: check each indicator top-to-bottom; use the first match.

If tests fail: STOP. Report the failure output. Do not proceed.
If no test command detected: warn the user and ask whether to proceed without tests.

通过

references/project-detection.md

从项目配置中检测测试命令：

标识规则	测试命令
`Makefile` 包含 `test` 目标	`make test`
`package.json` 包含 `test` 脚本	`<检测到的包管理器> run test`
`pyproject.toml` 包含pytest配置	`uv run pytest` （或检测到的运行器）
存在 `Cargo.toml`	`cargo test`
存在 `go.mod`	`go test ./...`
同时存在 `Gemfile` 和 `Rakefile`	`bundle exec rake test`

检测顺序：从上到下检查所有标识，使用第一个匹配的命令。

如果测试失败：终止流程，上报失败输出，不要继续后续步骤。
如果没有检测到测试命令：警告用户，询问是否跳过测试继续执行。

Step 4: Pre-Landing Review

步骤4：落地前评审

Invoke the

pre-landing-review

skill if available. Otherwise, perform a lightweight diff review against the default branch:

bash

git diff origin/<default-branch>...HEAD

Review the diff for:

Obvious bugs or logic errors
Security concerns (credentials, injection vectors)
Missing error handling on new code paths

Classification:

CRITICAL findings: STOP. Resolve before proceeding.
INFORMATIONAL findings: note them for inclusion in the PR description. Proceed.

如果有

pre-landing-review

技能则调用该技能，否则基于默认分支做轻量diff评审：

bash

git diff origin/<default-branch>...HEAD

评审diff时重点关注：

明显的Bug或逻辑错误
安全隐患（凭证、注入风险）
新代码路径缺少错误处理

评审结果分类：

严重问题：终止流程，解决问题后再继续。
提示类问题：记录问题用于PR描述中，继续后续步骤。

Step 5: Version Bump

步骤5：版本升级

Detect the version strategy from project configuration using

references/project-detection.md

Indicator	Version Location
`VERSION` file	Update file contents directly
`package.json` `version` field	Update the field
`pyproject.toml` `version` field	Update the field
`Cargo.toml` `version` field	Update the field
Git tags only	Create tag at push time

Default bump level: PATCH.

For MINOR or MAJOR bumps: STOP. Confirm with the user before proceeding.
If no version strategy detected: skip the version bump entirely. Note the skip in the PR description.

通过

references/project-detection.md

从项目配置中检测版本管理策略：

标识规则	版本位置
存在 `VERSION` 文件	直接更新文件内容
`package.json` 的 `version` 字段	更新该字段
`pyproject.toml` 的 `version` 字段	更新该字段
`Cargo.toml` 的 `version` 字段	更新该字段
仅使用Git标签	推送代码时创建标签

默认升级级别：PATCH（修订版）。

如果是**MINOR（次版本）或MAJOR（主版本）**升级：终止流程，向用户确认后再继续。
如果没有检测到版本管理策略：跳过版本升级步骤，在PR描述中记录跳过说明。

Step 6: Update Changelog

步骤6：更新变更日志

If
```
CHANGELOG.md
```
exists: prepend an entry in Keep a Changelog format.
If no changelog file exists: skip.

Auto-generate the entry from commit messages since the last tag or release. Group entries by conventional commit type:

markdown

undefined

如果存在
```
CHANGELOG.md
```
：按照Keep a Changelog格式在顶部添加变更条目。
如果不存在变更日志文件：跳过该步骤。

基于上一个标签或发布之后的提交信息自动生成变更条目，按照约定式提交类型分组：

markdown

undefined

[<new-version>] - <date>

[<新版本号>] - <日期>

Added

新增

feat: ...

feat: ...

Fixed

修复

fix: ...

fix: ...

Changed

变更

refactor: ...

---

refactor: ...

---

Step 7: Create Bisectable Commits

步骤7：创建可二分定位提交

Organize staged changes into logical, bisectable commit groups in this order:

Infrastructure / config changes — build files, CI config, dependencies
Models / services / core logic — domain layer, business rules
Controllers / views / API endpoints — presentation and routing
Version bump + changelog — always last

Each commit uses a descriptive conventional commit message. Each commit should pass tests independently when possible (verify if CI turnaround allows it; otherwise trust the ordering).

If all changes are already committed in a reasonable structure, skip reorganization.

将暂存的变更按以下顺序整理为逻辑独立、可二分定位的提交组：

基础设施/配置变更 — 构建文件、CI配置、依赖项
模型/服务/核心逻辑 — 领域层、业务规则
控制器/视图/API端点 — 展示层和路由
版本升级+变更日志 — 永远放在最后

每个提交都使用描述性的约定式提交信息，尽可能保证每个提交单独运行时都能通过测试（如果CI响应速度允许可以验证，否则信任排序逻辑）。

如果所有变更已经按照合理结构提交，跳过重组步骤。

Step 8: Push and Create PR

步骤8：推送代码并创建PR

bash

git push -u origin <current-branch>

Create the PR:

bash

gh pr create \
  --title "<conventional-format-title>" \
  --body "<generated-body>"

PR body includes:

Summary of changes (grouped by commit)
Test results (pass confirmation)
Version bump details (old → new, or "skipped")
Any INFORMATIONAL findings from Step 4

Output the PR URL as the final result.

bash

git push -u origin <current-branch>

创建PR：

bash

gh pr create \
  --title "<约定式格式标题>" \
  --body "<生成的描述内容>"

PR正文包含：

变更摘要（按提交分组）
测试结果（通过确认）
版本升级详情（旧版本→新版本，或“已跳过”）
步骤4中所有提示类评审结果

最终输出PR URL作为结果。

Stop Conditions

终止条件

The pipeline halts immediately and reports when any of these occur:

Condition	Step	Action
On default branch	1	Stop, instruct to create feature branch
Dirty working tree	1	Stop, list files, instruct to commit/stash
Behind remote	1	Stop, instruct to pull/rebase
Merge conflicts	2	Stop, report conflicting files
Test failures	3	Stop, report failure output
Critical review findings	4	Stop, resolve before proceeding
MINOR/MAJOR version bump	5	Stop, confirm with user

发生以下任意情况时，流水线会立即终止并上报：

条件	步骤	处理动作
当前为默认分支	1	终止，提示创建特性分支
工作树不干净	1	终止，列出文件，提示提交/暂存
落后于远程分支	1	终止，提示拉取/变基
合并冲突	2	终止，上报冲突文件
测试失败	3	终止，上报失败输出
严重评审问题	4	终止，解决后再继续
次版本/主版本升级	5	终止，向用户确认

Important Notes

重要说明

This skill modifies the repository: it creates commits, pushes code, and opens PRs.
All branch names and test commands are detected dynamically — nothing is hardcoded.
The version strategy is inferred from project files, not assumed.
If the
```
pre-landing-review
```
skill is not available, the review step degrades to a lightweight diff scan rather than skipping entirely.

该技能会修改代码仓库：会创建提交、推送代码、开启PR。
所有分支名称和测试命令都是动态检测的，没有硬编码内容。
版本管理策略是从项目文件推断的，不会做预设假设。
如果没有
```
pre-landing-review
```
技能，评审步骤会降级为轻量diff扫描，不会直接跳过。