factory/.claude/commands/release.md

description
生成 changelog、更新 SYS_VERSION、打 tag 并推到远端

发布一个新版本，遵循以下既定流程，严格按顺序执行，不要省略或调整步骤。

步骤

1. 生成 changelog 与版本号

执行：

bash update_changelog.sh

脚本会：

• 在 changelog.md 顶部写入 ## 3.1.YYYYMMDDHH，并附上自上一个 tag 起的 feat / fix / other 提交。
• 终端输出形如 当前版本号: 3.1.YYYYMMDDHH (请手动修改)。

从输出中抓取版本号（即 3.1.YYYYMMDDHH），后续步骤记作 <VER>。

2. 更新 server/settings.py 的 SYS_VERSION

把 SYS_VERSION = '<旧版本>' 改为 SYS_VERSION = '<VER>'。

该字段是项目里唯一权威的版本号，前端 /swagger 也读它。

3. 检查 changelog 顶部内容

Read 一下 changelog.md 头 ~20 行，确认：

• 顶部是 ## <VER>
• 自上次 tag 之后的提交都被分类列出。
• 如有内容明显不对（例如重复段、无关分类），先与用户确认，不要直接打 tag。

4. 提交 + 打 tag + 推送

参考过往风格（commit message 用 release: <VER>，tag 名直接用版本号、无 v 前缀）：

git add changelog.md server/settings.py
git commit -m "release: <VER>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
git tag <VER>
git push
git push origin <VER>

可以串成一个 && 链一次执行。

5. 汇报

向用户简述：

• 本次版本号 <VER>。
• changelog 顶部新增了多少行 / 包含哪几类提交。
• commit hash、tag 名、master / tag 都已推到 origin。

注意事项

• 不要自己编版本号：始终用 update_changelog.sh 输出里的那一个，不要试图改格式或日期。
• SYS_VERSION 是必须改的：脚本只更新 changelog.md，settings 必须手动同步，否则上线后接口返回的版本号还是旧的。
• CRLF 警告可忽略：Windows 上 git commit 会提示 LF will be replaced by CRLF，不是错误。
• 打 tag 前确认 working tree 干净：除了本次 commit 的两个文件外，不应有其他未追踪/未提交的改动混进 release commit。如有，先单独 commit 或 stash。
• 失败回滚：如果 push 失败需要回退，删除本地 tag (git tag -d <VER>) 与撤销 commit (git reset --soft HEAD^)；远端 tag 已 push 的删除需要先与用户确认。