changelog-writer

用途

Changelog Writer 专注于从 git 历史生成变更日志与发布相关文档。其职责范围限定为变更日志和发布文档，不用于 git 操作（应由 git-workflow 处理）、文档站点（应由 docs-steward 处理）或代码评审（应由 review 处理）。

主要能力

该技能包含五种模式：

1. 生成变更日志（默认）：从近期提交生成 Keep a Changelog 格式文档。先用 commit-classifier.py 按 conventional 类型分类提交并检测破坏性变更，再用 changelog-formatter.py 转换为 markdown，最后按 Added、Changed、Deprecated、Removed、Fixed、Security 分组并改写为面向用户的描述。

2. 发布说明（release <version>）：确定 last tag 到 HEAD 的范围，按用户影响而非提交类型分组（Highlights、Improvements、Bug Fixes、Breaking Changes、Contributors），将技术提交信息改写为面向用户的语言。

3. 破坏性变更（breaking）：检测向后不兼容的变更，识别受影响的 API/接口，描述变更与原因，提供 before/after 代码模式，评估影响范围，并按高/中/低严重度输出报告。

4. 迁移指南（migration <from> <to>）：针对每个破坏性变更说明变更内容、所需操作、代码示例与验证方式，按依赖顺序排列，组织为编号清单，包含迁移前检查清单与迁移后验证步骤。

5. 版本号升级建议（bump）：运行分类器读取 suggested_bump 字段，major（破坏性变更）、minor（新功能无破坏性变更）、patch（仅缺陷修复与非功能性变更），并引用具体提交作为证据。

使用方式

脚本调用命令：

• uv run python skills/changelog-writer/scripts/commit-classifier.py [--since <tag-or-date>] [--until <ref>] [--path <dir>]
• uv run python skills/changelog-writer/scripts/changelog-formatter.py --input <classified-json> [--format keepachangelog|github|simple]
• 破坏性变更检测：commit-classifier.py --breaking-only [--since <tag>]
• 迁移指南：commit-classifier.py --breaking-only --since <from> --until <to>
• 版本建议：commit-classifier.py --since <last-tag>

参考文件（一次加载一个）：references/changelog-conventions.md、references/commit-parsing.md。数据文件：data/changelog-formats.json、data/breaking-change-patterns.json。

适用场景

需要根据 git 提交历史整理变更日志、准备版本发布说明、汇总破坏性变更、编写版本迁移指南或确定下一个语义化版本号时适用。

限制

• 只读操作：从不修改 git 历史，除 git log 和 git tag 外不运行任何 git 操作。
• 必须先运行 commit-classifier.py，不手动解析 git log。
• 不为未提交的变更生成变更日志，仅使用已提交历史。
• 破坏性变更必须在所有输出格式中显著标注。
• 提交信息必须改写为面向用户的语言，原始提交文本不直接作为变更日志。
• 迁移指南中每个破坏性变更都必须包含 before/after 代码示例。
• 版本升级建议必须引用具体提交作为证据。
• 遇到非 conventional 格式的提交时按尽力启发式分类并标记不确定性。
• 除非用户另有指定，否则以最近的 tag 作为基线。