jackin-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

jackin-release

Cut a release. The only irreversible skill in the suite —

cargo release --execute

bumps the version, rewrites the changelog header, tags, and pushes. Hard-gated on one explicit operator "yes"; nothing releases on assumption.

Orchestrates

jackin-release-check

(the gates) and

jackin-release-notes

(the changelog), then recommends a version from the changelog shape and cuts.

执行版本发布。这是套件中唯一不可撤销的skill——

cargo release --execute

会更新版本号、重写变更日志标题、打标签并推送。必须经过操作人员明确输入“yes”才能执行，不会自动发布。

该工具会协调

jackin-release-check

（就绪检查）和

jackin-release-notes

（变更日志生成），然后根据变更日志的内容推荐版本号并完成发布。

When to use

使用场景

The operator asks to cut / ship / release a version.

操作人员要求执行版本发布/上线操作时。

When NOT to use

不适用场景

Just checking readiness →
```
jackin-release-check
```
.
Just updating the changelog →
```
jackin-release-notes
```
.

仅需检查发布就绪状态 → 使用
```
jackin-release-check
```
。
仅需更新变更日志 → 使用
```
jackin-release-notes
```
。

Prerequisites

前置条件

cargo-release

installed;

gh

authenticated;

release.toml

with

pre-release-replacements

for

CHANGELOG.md

;

CHANGELOG.md

with the

<!-- next-header -->

marker;

.github/workflows/ci.yml

已安装

cargo-release

；

gh

已完成身份验证；

release.toml

中配置了针对

CHANGELOG.md

的

pre-release-replacements

；

CHANGELOG.md

包含

<!-- next-header -->

标记；存在

.github/workflows/ci.yml

文件。

Process

流程

Gates. Run
```
jackin-release-check
```
. A red gate stops — show the report and name what to fix. Warns surface; ask whether to continue.
Done when every gate is green, or the operator accepted the warns.
Changelog. Run
```
jackin-release-notes
```
. Present the
```
[Unreleased]
```
section; let the operator re-classify or reword.
Done when the operator approves the changelog.
Recommend a version. Read the approved
```
[Unreleased]
```
buckets: any Removed or "breaking" entry → major; any Added → minor; only Fixed / Changed / Security / Deprecated → patch. Read the current version (
```
grep '^version' Cargo.toml
```
), compute the next, present the recommendation, wait.
Done when the operator confirms the bump level.

Commit the changelog. If

CHANGELOG.md

has uncommitted edits,

git add CHANGELOG.md && git commit -m "docs: update changelog for vX.Y.Z"

Final confirm. Show the summary — version, bump level, changelog shape, and the exact
```
cargo release <level> --execute
```
about to run (it bumps
```
Cargo.toml
```
, renames
```
[Unreleased]
```
to
```
[X.Y.Z] - <date>
```
via
```
release.toml
```
, tags, and pushes). Do not run it without an explicit "yes."
Done when the operator says "yes."
Cut.
```
cargo release <level> --execute
```
. On failure, show the error and stop.
Verify.
```
git tag -l "vX.Y.Z"
```
and
```
git ls-remote --tags origin "refs/tags/vX.Y.Z"
```
. Point the operator at the release workflow that now builds the artifacts.

就绪检查。运行
```
jackin-release-check
```
。若检查不通过（红色状态）则终止流程——展示检查报告并说明需要修复的内容。若仅为警告，则询问是否继续。
完成标志：所有检查项通过，或操作人员确认接受警告。
变更日志处理。运行
```
jackin-release-notes
```
。展示
```
[Unreleased]
```
部分内容，允许操作人员重新分类或修改措辞。
完成标志：操作人员确认变更日志内容。
推荐版本号。读取已确认的
```
[Unreleased]
```
分类内容：若包含Removed或“破坏性变更”条目 → 主版本（major）；若包含Added条目 → 次版本（minor）；仅包含Fixed / Changed / Security / Deprecated → 补丁版本（patch）。读取当前版本号（
```
grep '^version' Cargo.toml
```
），计算下一个版本号，展示推荐结果并等待确认。
完成标志：操作人员确认版本升级级别。

提交变更日志。若

CHANGELOG.md

存在未提交的修改，执行

git add CHANGELOG.md && git commit -m "docs: update changelog for vX.Y.Z"

。

最终确认。展示汇总信息——版本号、升级级别、变更日志结构，以及即将执行的
```
cargo release <level> --execute
```
命令详情（该命令会更新
```
Cargo.toml
```
版本号，通过
```
release.toml
```
将
```
[Unreleased]
```
重命名为
```
[X.Y.Z] - <date>
```
、打标签并推送）。必须得到明确的“yes”才能执行。
完成标志：操作人员输入“yes”。
执行发布。运行
```
cargo release <level> --execute
```
。若执行失败，展示错误信息并终止流程。
验证发布。执行
```
git tag -l "vX.Y.Z"
```
和
```
git ls-remote --tags origin "refs/tags/vX.Y.Z"
```
。引导操作人员查看负责构建产物的发布工作流。

Error recovery

错误恢复

Before
```
cargo release
```
: safe to fix and re-run — this skill re-validates everything.
During
```
cargo release
```
: check what committed or tagged. Tag created but unpushed →
```
git push origin vX.Y.Z
```
. Version commit without tag → reset and retry.
After: the release is done; a CI failure is a workflow issue, not a rollback.

在执行
```
cargo release
```
之前：可以安全修复问题后重新运行——该skill会重新验证所有内容。
在执行
```
cargo release
```
过程中：检查已提交或已打标签的内容。若标签已创建但未推送 → 执行
```
git push origin vX.Y.Z
```
。若已提交版本号变更但未打标签 → 重置并重试。
执行完成后：发布已完成；若CI失败属于工作流问题，无需回滚。

Common mistakes

常见错误

Running
```
cargo release
```
without the explicit "yes" — the one hard gate.
Letting a red readiness gate through to the cut.
Hand-editing the
```
[X.Y.Z]
```
version heading —
```
cargo-release
```
rewrites it via
```
release.toml
```
```
pre-release-replacements
```
; double-editing corrupts the release commit.

未得到明确“yes”就运行
```
cargo release
```
——这是唯一的强制检查项。
允许未通过的就绪检查项进入发布流程。
手动编辑
```
[X.Y.Z]
```
版本标题——
```
cargo-release
```
会通过
```
release.toml
```
的
```
pre-release-replacements
```
重写该标题；手动编辑会导致发布提交内容损坏。