changelog-writer

变更日志编写器

根据 Git 历史生成变更日志、发行说明、重大变更摘要、迁移指南和版本升级建议。

**范围：**仅限变更日志和发行文档。不适用于 Git 操作（git-workflow）、文档站点（docs-steward）或代码审查（review）。

分派

$ARGUMENTS	模式
空 / generate	根据近期提交生成变更日志
release <version>	为指定版本编写面向用户的发行说明
breaking	检测并总结重大变更
migration <from> <to>	生成两个版本之间的迁移指南
bump	根据变更推荐语义化版本升级
无法识别的输入	请求澄清并显示模式菜单

规范术语

术语	定义
conventional commit	遵循 type(scope): description 格式的提交
变更类型	分类：feat、fix、refactor、perf、docs、chore、test、ci、build、style
重大变更	不向后兼容的变更，以 ! 或 BREAKING CHANGE: 页脚标记
范围	受影响的组件，位于类型后面的括号中
变更日志条目	变更日志章节中的格式化条目
发行说明	面向用户的特定版本变更摘要
迁移指南	版本升级的分步说明
semver 升级	major（重大变更）、minor（feat）、patch（fix）建议
未发行	自上一个带标签版本以来的变更

模式 1：生成变更日志

默认模式。生成符合 Keep a Changelog 格式的文档。

步骤 1：分类提交

运行提交分类脚本：

uv run python skills/changelog-writer/scripts/commit-classifier.py [--since <tag-or-date>] [--until <ref>] [--path <dir>]

解析 JSON 输出。脚本会按 conventional commit 类型对每个提交分类，并检测重大变更。

步骤 2：格式化变更日志

运行变更日志格式化脚本：

uv run python skills/changelog-writer/scripts/changelog-formatter.py --input <classified-json> [--format keepachangelog|github|simple]

脚本会将分类后的提交转换为格式化的 Markdown。默认格式：Keep a Changelog。

步骤 3：审核和完善

• 按章节分组条目（新增、变更、弃用、移除、修复、安全）
• 将简短的提交信息改写为用户易读的描述
• 适当合并相关提交，整理为单个条目
• 确保醒目地标出重大变更

格式参考：阅读 references/changelog-conventions.md

模式 2：发行说明

release <version> 会生成完善的、面向用户的发行说明。

步骤 1：确定范围

确定范围：从上一个标签到 HEAD（如果版本已打标签，则取两个标签之间的范围）。

git log --oneline <previous-tag>..<version-or-HEAD>

步骤 2：分类和分组

使用适当的 --since 和 --until 标志运行 commit-classifier.py。按对用户的影响分组，而非按提交类型分组：

• 亮点 — 主要功能（前 3-5 项）
• 改进 — 功能增强、性能提升
• 错误修复 — 已解决的问题
• 重大变更 — 需要迁移的项目（链接到迁移模式）
• 贡献者 — 根据 Git 日志列出贡献者

步骤 3：编写发行说明

将技术性提交信息改写为面向用户的语言。参考：阅读 references/changelog-conventions.md 中的“发行说明风格”部分。

模式 3：重大变更

breaking 会扫描不向后兼容的变更。

步骤 1：检测

以检测重大变更为重点运行提交分类脚本：

uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only [--since <tag>]

步骤 2：补充信息

对于每项重大变更：

1. 找出受影响的 API/接口
2. 描述变更内容及原因
3. 提供变更前后的代码模式
4. 评估影响范围（受影响的使用者数量）

使用 data/breaking-change-patterns.json 中的模式进行特定语言的检测。

步骤 3：总结

输出重大变更报告，并根据影响范围和迁移工作量划分严重程度（高/中/低）。

模式 4：迁移指南

migration <from> <to> 会生成分步升级说明。

步骤 1：收集重大变更

运行提交分类脚本，查找两个版本之间的变更：

uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only --since <from> --until <to>

步骤 2：生成迁移步骤

对于每项破坏性变更，请提供：

1. 变更内容 — 旧行为与新行为
2. 所需操作 — 具体迁移步骤
3. 代码示例 — 变更前后的代码片段
4. 验证 — 如何确认迁移成功

按照依赖关系排列步骤（必须先完成的变更排在前面）。

步骤 3：编写指南

将内容整理为编号清单。包含迁移前检查清单（备份、测试套件通过）和迁移后验证步骤。

参考：阅读 references/changelog-conventions.md 中的“迁移指南结构”章节。

模式 5：版本升级

bump 会推荐下一个语义化版本。

步骤 1：分析

运行提交分类器：

uv run python skills/changelog-writer/scripts/commit-classifier.py --since <last-tag>

从 JSON 输出中读取 suggested_bump 字段。

步骤 2：报告

提供建议并说明依据：

升级类型	原因
major	检测到破坏性变更：列出这些变更
minor	新增功能，且无破坏性变更
patch	仅包含错误修复和非功能性变更

展示支持该建议的提交证据。如果提交含义模糊（不符合约定格式），请标明不确定性并请求确认。

参考文件

一次只加载一个参考文件。

文件	内容	阅读时机
references/changelog-conventions.md	Keep a Changelog 格式、发行说明风格、迁移指南结构、语义化版本决策树	任何模式下格式化输出时
references/commit-parsing.md	约定式提交解析规则、破坏性变更检测启发式规则	理解分类器输出或处理边缘情况时

数据文件	内容	使用方
data/changelog-formats.json	格式模板（Keep a Changelog、GitHub Releases、简易格式）	changelog-formatter.py
data/breaking-change-patterns.json	特定语言的破坏性变更检测模式	commit-classifier.py、模式 3 补充信息

脚本	用途
scripts/commit-classifier.py	解析 git 日志，按约定类型分类，并检测破坏性变更
scripts/changelog-formatter.py	将分类后的提交 JSON 转换为格式化的变更日志 Markdown

关键规则

1. 切勿修改 git 历史记录，或执行除 git log 和 git tag 之外的 git 操作——此技能仅用于读取
2. 格式化前始终运行 commit-classifier.py——不要手动解析 git 日志
3. 每种输出格式都必须醒目地指出破坏性变更
4. 将提交消息改写为用户易懂的语言——原始提交文本不是变更日志
5. 每项破坏性变更的迁移指南都必须包含变更前后的代码示例
6. 版本升级建议必须引用具体提交作为依据
7. 遇到不符合约定格式的提交时，应根据尽力而为的启发式规则进行分类，并标明不确定性
8. 不要为未提交的变更生成变更日志——仅处理已提交的历史记录
9. 除非用户另有指定，否则始终将上一个标签作为基准
10. 在发行说明中注明贡献者——从 git 日志的作者字段中提取