jackin-release

jackin-release

切出一个版本。这是套件中唯一不可逆的技能——cargo release --execute 会提升版本号、重写变更日志标题、创建标签并推送。必须经过操作员明确说出一次“yes”的硬性门槛；绝不基于假设发布。

负责协调 jackin-release-check（门槛检查）和 jackin-release-notes（变更日志），然后根据变更日志的内容建议版本号并切出版本。

适用场景

• 操作员要求切出 / 发布一个版本。

不适用场景

• 只检查是否已准备就绪 → jackin-release-check。
• 只更新变更日志 → jackin-release-notes。

前置条件

已安装 cargo-release；gh 已完成身份验证；release.toml 中配置了针对 CHANGELOG.md 的 pre-release-replacements；CHANGELOG.md 中有 `` 标记；存在 .github/workflows/ci.yml。

流程

1. 门槛检查。 运行 jackin-release-check。任何红色门槛都会停止流程——展示报告并指出需要修复的内容。警告会显示出来；询问是否继续。

   完成条件：所有门槛均为绿色，或操作员接受了警告。

2. 变更日志。 运行 jackin-release-notes。展示 [Unreleased] 部分；允许操作员重新分类或改写。

   完成条件：操作员批准变更日志。

3. 建议版本号。 阅读已批准的 [Unreleased] 分类：任何 Removed 或“breaking”条目 → major；任何 Added → minor；只有 Fixed / Changed / Security / Deprecated → patch。读取当前版本（grep '^version' Cargo.toml），计算下一个版本号，给出建议并等待。

   完成条件：操作员确认版本提升级别。

4. 提交变更日志。 如果 CHANGELOG.md 有未提交的编辑，运行 git add CHANGELOG.md && git commit -m "docs: update changelog for vX.Y.Z"。

5. 最终确认。 展示摘要——版本号、提升级别、变更日志内容，以及即将运行的确切命令 cargo release <level> --execute（该命令会提升 Cargo.toml 中的版本号，通过 release.toml 将 [Unreleased] 重命名为 [X.Y.Z] - <date>，创建标签并推送）。未获得明确的“yes”前，切勿运行。

   完成条件：操作员说“yes”。

6. 切出版本。 运行 cargo release <level> --execute。如果失败，展示错误并停止。

7. 验证。 运行 git tag -l "vX.Y.Z" 和 git ls-remote --tags origin "refs/tags/vX.Y.Z"。告知操作员查看现已开始构建制品的发布工作流。

错误恢复

• 运行 cargo release 之前：可以安全修复并重新运行——此技能会重新验证所有内容。
• 运行 cargo release 期间：检查哪些内容已提交或创建了标签。标签已创建但尚未推送 → git push origin vX.Y.Z。版本提交已创建但没有标签 → 重置并重试。
• 之后：发布已完成；CI 失败属于工作流问题，不应回滚。

常见错误

• 未获得明确的“yes”就运行 cargo release——这是唯一的硬性门槛。
• 让红色的就绪检查门槛放行并继续切出版本。
• 手动编辑 [X.Y.Z] 版本标题——cargo-release 会通过 release.toml 中的 pre-release-replacements 重写它；重复编辑会破坏发布提交。