Changelog Generator 是一个将 git 历史转化为发布文档的技能工具。其核心思路是:读取符合 Conventional Commits 规范的提交记录,判定这些提交所隐含的语义化版本增量,并按 Keep a Changelog 的结构渲染发布条目。工具强调机械性——由结构化提交按规则生成的变更日志不会悄悄遗漏破坏性变更,而合并前运行的提交消息 linter 则保证结构本身可靠。生成与校验构成一个闭环。
适用场景:发布标签前撰写条目并选定版本号;在 CI 中自动将发布说明附加到 GitHub/GitLab release;在 PR 检查中拦截无法转化为发布说明的提交消息;在 monorepo 中按单个包的提交范围生成条目;将原始 git log 输出转换为面向用户的说明。该技能不用于为没有对应提交的变更编造描述,变更日志条目必须可追溯到真实存在的提交。
核心能力:按 Conventional Commit 规则解析提交消息,包括 type(scope)!: 形式与 BREAKING CHANGE: 页脚;检测提交流隐含的 semver 增量(major / minor / patch / none);将提交分组到 Keep a Changelog 章节;输出 Markdown 格式的 CHANGELOG.md 或供 CI 使用的机器可读 JSON;对提交消息执行 lint 并在违规时以非零退出码结束。
主要工作流:
- 从 git 区间生成条目:python3 scripts/generate_changelog.py --from v1.4.0 --to HEAD。读取当前仓库的 git log;省略 --from 时自动使用最近标签,若无标签则使用全部历史。
- 仅计算下一版本而不写入:python3 scripts/generate_changelog.py --from v1.4.0 --next --format json。输出增量与结果版本号,可在发布任务中先确定标签名再起草条目。
- 从文件或 stdin 生成条目:git log --format='%s%n%b%n---COMMIT---' v1.4.0..HEAD | python3 scripts/generate_changelog.py --input - --version 1.5.0。任何以空行加 ---COMMIT--- 标记分隔提交的输入均可使用,调用方已有日志时脚本无需再执行 shell 命令。
- 将条目前置写入 CHANGELOG.md:python3 scripts/generate_changelog.py --from v1.4.0 --version 1.5.0 --update CHANGELOG.md。--update 在 # Changelog 标题下前置新条目,保留所有现有章节不动;若版本已存在则拒绝写入。
- 合并前 lint 提交:python3 scripts/commit_linter.py --range origin/main..HEAD。任何违规均以退出码 1 结束,并给出问题消息与原因;CI 集成方式参见 references/ci-integration.md。
Conventional Commit 规则:格式为 <type>(<scope>): <description>。类型与章节映射:feat 新能力→Added;fix 缺陷修复→Fixed;perf 性能改进→Changed;refactor 重构(行为不变)→Changed;docs 仅文档→Documentation;test 仅测试→默认省略;build 构建系统或依赖→Changed;ci CI 配置→默认省略;chore 维护→默认省略;security 安全修复→Security;deprecated 标记待移除→Deprecated;remove 移除能力→Removed;revert 回滚先前提交→Changed。破坏性变更有两种声明方式且均被识别:feat(api)!: drop the v1 tasks endpoint,或 feat(api): drop the v1 tasks endpoint 后跟 BREAKING CHANGE: clients must migrate to GET /v2/tasks.。SemVer 映射:存在任何破坏性变更→major;存在 feat 且无破坏性变更→minor;其余→patch;无可发布提交→不升版本(不发布)。仅含 chore 与 test 的提交流不产生条目,为其发布会让消费者误以为有变化。
提交质量标准:可接受的提交消息应无需手工改写即可成为变更日志行,例如 feat(billing): add proration for mid-cycle plan changes;不可接受的包括 fixed stuff、update code、wip、WIP: almost done。linter 检查结构而非品味,它无法判断描述是否良好,但能保证每个合并的提交都可被解析,这是生成可信的前提。
破坏性变更处理:每次 major 升级都需要迁移指引。仅有“移除 v1 端点”而无替代调用方式的变更日志会制造支持工单。当存在 BREAKING CHANGE: 页脚时,应原样作为 BREAKING: 条目放入 Changed 章节,页脚是作者书写迁移路径之处,必须不经编辑地保留。
常见陷阱:将合并提交解析为功能(以 Merge 开头的消息两个脚本均忽略);摘要含糊无法成为发布说明;遗漏破坏性变更的迁移指引;覆盖历史章节(只前置不重写,历史应只追加);对不可发布的提交发版;引用不存在的标签——若 --from 指向未知 ref,应显式失败而非静默从全部历史生成。
发布前核验:版本符合提交隐含的增量;渲染章节中无合并提交或 chore 噪音;每个破坏性变更都有来自页脚的迁移说明;日期为发布日期而非最新提交日期;新条目下方现有章节完好;即将创建的标签与标题中的版本一致。