changelog-composer

变更日志撰写器

将原始 Git 历史记录和 PR 描述转换为润色后的、适合目标受众的变更日志。解析约定式提交，按影响类别对变更分类，过滤仅供内部使用的修改，并生成带 PR 链接的结构化发布说明——遵循 Keep a Changelog 规范。

参考文件

文件	内容	加载时机
references/conventional-commits.md	提交类型解析、作用域提取、重大变更标记	仓库使用约定式提交时
references/categorization-rules.md	变更分类逻辑、受众筛选、严重程度排序	始终
references/audience-filter.md	面向用户的变更与内部变更检测、排除模式	始终
references/changelog-formats.md	Keep a Changelog、GitHub Releases、公告文案模板	需要选择格式时

前置条件

• git — 访问仓库历史记录
• gh（可选）— 用于提取 PR 描述的 GitHub CLI
• 用于确定发布边界的标签策略（semver 标签）

工作流

阶段 1：收集原始变更

收集上一个版本到当前状态之间的所有变更：

1. 确定边界 — 查找上一个发布标签：git describe --tags --abbrev=0。 如果不存在标签，则使用初始提交或用户指定的起始点。
2. 提取提交 — git log <last-tag>..HEAD --oneline --no-merges
3. 提取 PR 标题 — gh pr list --state merged --base main --search "merged:>YYYY-MM-DD" 或解析合并提交消息。
4. 解析约定式提交 — 如果仓库遵循约定式提交 （feat:、fix:、docs: 等），则提取类型、作用域和描述。请参阅 references/conventional-commits.md。
5. 收集重大变更标记 — 查找提交正文中的 BREAKING CHANGE:、类型后的 !（feat!:），或 PR 描述中的明确标注。

阶段 2：对变更分类

按影响对每项变更进行分类：

类别	约定式提交类型	标记
重大变更	feat!:、BREAKING CHANGE:	API 移除、签名变更、行为变更
功能	feat:	新能力、新端点、新命令
修复	fix:	错误修正、错误处理改进
性能	perf:	速度提升、内存占用减少
文档	docs:	README、API 文档、指南
内部变更	chore:、ci:、refactor:、test:、build:	对用户无影响

对于不使用约定式提交的仓库，请阅读提交消息和变更文件进行分类。公共 API 的代码变更 → 功能或修复。仅涉及测试的变更 → 内部变更。

第 3 阶段：筛选受众相关内容

1. 默认排除内部变更：

   • CI/CD 配置变更
   • 新增或修改测试
   • 依赖项升级（与安全相关的除外）
   • 不改变行为的代码重构
   • 构建系统变更

2. 仅在以下情况下纳入内部变更：

   • 这些变更代表用户应了解的重大架构调整
   • 这些变更会影响开发工作流（如贡献指南变更）
   • 更新日志面向开发者，而非最终用户

3. 突出显示重大变更——始终置于最前，并始终提供迁移指南。

第 4 阶段：撰写条目

为每项纳入的变更撰写易于理解的描述：

1. 先说明影响——“用户现在可以……”或“修复了……问题”
2. 描述具体——“将大文件处理的内存使用量减少了 40%”，而不是“性能改进”
3. 为重大变更提供迁移指南——说明用户必须做出哪些更改
4. 链接到来源——PR 编号、问题编号或提交哈希

第 5 阶段：输出

按严重程度排序，并以所需格式整理更新日志：

1. 重大变更（始终置于最前）
2. 功能
3. 修复
4. 性能
5. 文档

输出格式

## [{version}] - {YYYY-MM-DD}

### Breaking Changes
- **`function_name` parameter renamed** — `old_param` is now `new_param`.
  Migration: find/replace `old_param=` with `new_param=` in all call sites. ([#{pr}]({url}))

### Features
- **{Feature name}** — {What it enables and why it matters}. ([#{pr}]({url}))

### Fixes
- Fixed {symptom} when {condition}. ([#{pr}]({url}))

### Performance
- {Operation} is now {X}x faster / uses {X}% less memory. ([#{pr}]({url}))

### Documentation
- Added {guide/reference} for {topic}. ([#{pr}]({url}))

配置范围

模式	输入	输出	使用场景
release	标签到 HEAD	完整的更新日志条目	准备版本发布
sprint	日期范围或提交范围	变更摘要	Sprint 回顾、状态更新
pr	单个 PR	一行更新日志条目	PR 描述模板

校准规则

1. 首先关注用户影响。 每个条目都应回答“这对用户意味着什么？”，而不是“开发者做了什么？”
2. 重大变更不可妥协。 绝不省略或隐藏重大变更。它们必须放在最前，并附上迁移指南。
3. 具体胜过含糊。 “修复了慢速连接下的登录超时问题”胜过“修复了错误”。“为报告添加了 CSV 导出”胜过“新增功能”。
4. 为所有内容添加链接。 每个条目都要链接到来源 PR 或问题。想要了解详情的用户可以点击链接。
5. 排除无关内容。 内部重构、依赖项升级和 CI 变更不应出现在面向用户的更新日志中，除非它们会对用户产生可见影响。

错误处理

问题	解决方案
仓库中不存在标签	请提供起始提交或日期。如果仓库较小，则默认从初始提交开始。
仓库未使用约定式提交	阅读提交消息和变更文件进行分类。注明分类准确性有所降低。
PR 描述为空或质量较差	改用提交消息。标记可能需要人工审核的条目。
变更分类不明确	新增内容默认归为“功能”，修改内容默认归为“修复”。将不确定的条目标记为待审核。
单个版本的变更过多	按组件或模块分组。考虑是否应拆分版本发布。
合并提交掩盖了单项变更	使用 --no-merges 跳过合并提交。解析已合并 PR 中的单项提交。

不应使用 Compose 的情况

如果出现以下情况，请提出异议：

• 用户想要未经审核自动发布发行说明——变更日志需要人工判断
• 仓库没有有意义的提交历史（只有一个包含所有内容的“初始提交”）
• 请求的是营销文案，而非技术发行说明——这属于不同的技能
• 更改尚未合并——变更日志应记录已发布的更改，而非进行中的工作