用途:撰写或修复 CHANGELOG.md,让决定是否升级的用户读一节就能知道改了什么、哪里破坏了、该怎么做。变更日志是产品界面,不是 git log 转储。
核心约束:写面向用户的变化,而非提交标题;不得编造或倒填条目,每条必须对应真实已发布变更;始终在顶部保留 ## [Unreleased] 区段;版本标题须与真实 tag 和 semver 一致。
结构:遵循 Keep a Changelog,最新版本在前,标题形如 ## [version] - YYYY-MM-DD,日期用 ISO 8601;[Unreleased] 无日期置顶;提供对比链接。六个分组:Added、Changed、Deprecated、Removed、Fixed、Security,无条目的组省略。
Semver 对齐:Removed 或破坏性 Changed 对应 Major;向后兼容的 Added 对应 Minor;仅 Fixed/Security 对应 Patch;破坏性变更标 BREAKING: 前缀。
快速开始:在仓库根定位或创建 CHANGELOG.md;用 git tag --sort=-creatordate 和 git log --oneline v1.1.0..v1.2.0 从 tag 间提交重建历史;分组、把提交语言改写为用户语言、核对版本顺序与 semver,运行 bash scripts/validate.sh 并报告结论。
审查流程:确认结构骨架;逐条按用户视角阅读并改写实现细节;检查分组;核对版本标题与真实 tag 及 bump 类型;验证对比链接;确认持续维护机制。
维护:每个含变更的 PR 在 [Unreleased] 对应组添加一行;发版时把 [Unreleased] 改名为带日期版本、新建空的 [Unreleased]、更新 diff 链接并打 tag。
输出:工作质量报告(修复时同时写入 CHANGELOG.md),含 Verdict、Findings、Changes、Verification、Residual risk。
限制:资料未提供脚本内容、安装方式与价格信息。