release-bump

发布版本升级

目标

定稿变更日志草稿，在所有受跟踪文件中升级版本号，并创建一个带标签的发布提交。此技能运行完成后，仓库中会有一个干净的发布提交和标签，随时可以推送。

前提条件

• 已安装并认证 gh CLI（gh auth status）。
• 已安装 bumpversion（pip install bumpversion 或项目中 venv 已提供）。
• CHANGELOG.md 的 [Unreleased] 部分应已包含发布说明。如果为空或已过时，请先运行 draft-release-notes 技能。

工作流

1. 确认工作区干净（CHANGELOG.md 除外，其中可能包含草稿）。

   git status --porcelain
   

   只应修改 CHANGELOG.md（以及可选的 .agents/ 文件）。如果有其他未提交的更改，请停止并让用户先提交或暂存它们。

2. 确定升级级别。

   如果用户未指定，请询问：patch、minor 或 major。检查当前版本：

   grep '^current_version' .bumpversion.cfg
   

3. 为变更日志打上版本标记。

   从 CHANGELOG.md 中读取当前的 [Unreleased] 内容。计算新版本号（基于升级级别和当前版本）。然后：

   a. 将 ## [Unreleased] 部分的正文替换为空占位符。 b. 在 ## [Unreleased] 之后立即插入一个新的已打标版本部分：

   ## [Unreleased]
   
   ## [X.Y.Z] - YYYY-MM-DD
   
   <the content that was in [Unreleased]>
   

   c. 更新文件底部的引用链接：

   • 将 [Unreleased] 链接改为与新标签进行比较
   • 为新版本添加新链接

   [Unreleased]: https://github.com/jamiepine/voicebox/compare/vX.Y.Z...HEAD
   [X.Y.Z]: https://github.com/jamiepine/voicebox/compare/vPREVIOUS...vX.Y.Z
   

4. 暂存变更日志。

   git add CHANGELOG.md
   

5. 运行 bumpversion。

   bumpversion --allow-dirty <patch|minor|major>
   

   需要 --allow-dirty 标志，因为 CHANGELOG.md 已被暂存。bumpversion 将：

   • 更新所有受跟踪文件中的版本字符串（参见 .bumpversion.cfg）
   • 创建一条提交信息为 Bump version: X.Y.Z -> A.B.C 的提交
   • 创建标签 vA.B.C

   已暂存的 CHANGELOG.md 将自动包含在此提交中。

6. 验证结果。

   git show --name-only --stat HEAD
   git tag --list "v*" --sort=-v:refname | head -n 5
   

   确认该提交包含：

   • CHANGELOG.md
   • .bumpversion.cfg
   • tauri/src-tauri/tauri.conf.json
   • tauri/src-tauri/Cargo.toml
   • package.json
   • app/package.json
   • tauri/package.json
   • web/package.json
   • backend/__init__.py

   确认新标签已存在。

7. 不要推送，除非用户明确要求。报告标签名称并建议：

   Ready to push. When you're ready:
     git push origin main --follow-tags
   

版本计算参考

给定当前版本 X.Y.Z：

• patch -> X.Y.(Z+1)
• minor -> X.(Y+1).0
• major -> (X+1).0.0

错误恢复

• 如果 bumpversion 失败，标签将不存在。修复问题并重新运行 —— 只要标签尚未存在，bumpversion 就是幂等的。
• 如果需要撤销发布提交（在推送之前）：git tag -d vX.Y.Z && git reset --soft HEAD~1
• 切勿修改已推送的发布提交。

备注

• 当标签被推送后，发布 CI（.github/workflows/release.yml）会自动从 CHANGELOG.md 中提取匹配的版本部分，并将其用作 GitHub Release 正文。无需手动复制粘贴。
• 发布提交信息由 .bumpversion.cfg 控制（Bump version: X.Y.Z -> A.B.C）。请勿覆盖它。
• 如果需要在事后手动更新 GitHub Release 正文：gh release edit vX.Y.Z --notes-file <(sed -n '/## \[X.Y.Z\]/,/## \[/p' CHANGELOG.md | head -n -1)