hhu3637kr/skills/version-release

Version Release

运行契约

核心原则

1. 计划入版 vs 实际发布严格分离：plan.html 记录最初想做什么，releases/<tag>/release-report.html 记录本发布真正打包了哪些 Spec、代码提交 SHA 与构建产物。
2. 提测冻结分支 `release/<version>` 承载：从 dev 拉出提测分支，后续只允许合入针对该版本的缺陷修复（fix/*），主开发线 dev 可继续推进后续版本工作。
3. 主干合流与 Tag 不可变：验收通过后通过 PR/MR 合入主干（master），在合并提交上打不可变 Git Tag（vX.Y.Z）。
4. 强制回流 `dev` 闭环：发版后必须立即将 release/<version> 合回 dev，确保提测期间打的补丁绝不丢失。

工作流程

阶段一：提测冻结（进入「验收中」）

1. 核对前置条件：检查 version-context.md，确认所有规划入版的 Spec 均已合并入 dev 且单项测试通过。未完成且确定延期的 Spec 先调用 version-update 移出。
2. 更新版本账本并创建提测集成分支：

• 将 version-context.md 状态改为 验收中，记录冻结时间与冻结提交 SHA。
• 提交账本变更并拉出提测分支：

``bash git checkout dev git pull origin dev git add "spec/versions/<version>/version-context.md" git commit -m "docs(version): <version> 提测冻结，状态进入验收中" git checkout -b release/<version> git push -u origin release/<version> ``

1. 提测期间修复：若测试发现跨模块集成缺陷，从 release/<version> 拉出 fix/<slug> 分支，修复并验证后提 PR/MR 合回 release/<version>。

阶段二：正式发版（进入「已发布」）

1. 执行全量回归测试：在 release/<version> 分支上执行全量测试套件与端到端业务流验证，获取新鲜测试输出。
2. 生成发版交付报告 `release-report.html`：

创建 spec/versions/<version>/releases/<tag>/release-report.html，使用 html-report/templates/release-report-template.html 骨架，遵循 html-report 规范（声明 rk:version、rk:type="release-report"、引用 assets 为 5 层相对路径 ../../../../../html-report/assets/），必须包含：

• 实际纳入的 Spec 列表（含各 Spec 路径与 PR/MR 链接）
• 全量回归测试命令、退出码与证据日志位置
• 候选提交 SHA 与构建镜像/产物摘要
• 部署变更说明（配置项、数据迁移脚本等）
• 必需图（机检强制）：release-report 至少包含指标卡（rk-kpis：纳入 Spec 数、回归通过数、失败数），放在结论块之后、第一个正文章节结束之前。正文每 800 字至少配一张图，单段（<p> / <li>）不超过 150 字。能用图表达的数字、顺序、结构先画图，文字只补图里没有的原因、限制和下一步。画法见 html-report/references/figures.md
• 写完按 html-report「结构机检」一节的命令运行 check-report.js，退出码为 0 才算完成

1. 提交发版报告（只提报告，不改账本）：

• 此时主干合并尚未发生，Tag 尚未打在 master 上，状态未最终闭环。
• 仅提交发版报告目录，不修改 version-context.md，避免账本提前进入终态：

``bash git add "spec/versions/<version>/releases/<tag>" git commit -m "docs(release): 产出 <tag> 发布报告与测试证据" git push origin release/<version> ``

1. 面向主干发起 PR/MR、合并并打 Tag：

• 发起从 release/<version> 到 master 的发布 PR/MR 并完成合并。
• 切换到主干拉取最新提交，在主干合并提交上打发布 Tag 并推送：

``bash git checkout master git pull origin master git tag -a <tag> -m "release: <tag>" git push origin <tag> ``

1. 回流 `dev` 并在 `dev` 上执行唯一一次账本提交：

• 将 release/<version>（含发版报告与提测期 fix）通过 PR/MR 合回 dev（或在 dev 上 fast-forward / merge）。
• 切换到 dev 分支，更新 spec/versions/<version>/version-context.md：
• 状态改为 已发布
• 登记发布 Tag（<tag>）、发布时间与主干 commit SHA
• 在 dev 上做唯一一次账本提交并推送，彻底避免多次提交与账本回流冲突：

``bash git checkout dev git pull origin dev git add "spec/versions/<version>/version-context.md" git commit -m "docs(version): 更新 <version> 版本账本状态为已发布（<tag>）" git push origin dev ``

1. AWR 运行时状态同步（若有对应发布任务）：

AWR 0.5.0 中 Session 绑定原子 WorkItem。若当前版本在台账中声明了专属版本发版任务（如 <VERSION-WORK-ID>，例 TASK-RELEASE-<version>），提交发版检查点并正常关闭会话： ``bash AWR_CP=.agents/skills/scripts/rk-awr-checkpoint.sh; [ -f "$AWR_CP" ] || AWR_CP=scripts/rk-awr-checkpoint.sh bash "$AWR_CP" --work <VERSION-WORK-ID> --agent version-release --digest "version-release: 版本 <version> 已完成发布并打 Tag <tag>，状态更新为已发布" --next-action "version-end: 准备复盘收尾" --end ``