Changelog 生成

Changelog 生成

目标

从项目的 git 提交历史中提取变更，生成结构化、面向读者的 changelog 或 release notes。核心工作是两步转换：先把散乱的 commit 归类（新功能 / 改进 / 修复 / 破坏性变更等），再把工程师视角的技术描述改写成目标读者（终端用户、集成方开发者、或应用商店审核）看得懂、关心的语言。

一条 commit fix: null check in auth middleware 对开发者有意义，但用户想看到的是"修复了部分场景下登录失败的问题"。本 skill 就是完成这层翻译，并按版本 / 时间范围组织成规范文档。

工作流步骤

步骤 1：确认输入参数

动手前明确以下信息，缺失的先问用户或用合理默认：

• 仓库位置：默认当前工作目录；若用户给了路径则 cd 到对应目录操作。
• 范围：三选一
  • 版本区间：如 v2.4.0..v2.5.0 或 v2.4.0..HEAD
  • 时间范围：如 2024-03-01 到 2024-03-15
  • 相对范围：如"本周""最近 20 次提交"
• 目标读者：终端用户（弱化技术）/ 开发者集成方（保留 API 细节）/ 应用商店（简短生动、≤200 字）。读者不同，改写力度完全不同。
• 输出格式与语言：Markdown（默认）/ 纯文本；中文 / 英文。
• 产品名与版本号：用于标题。

步骤 2：用 Bash 抓取提交历史

用 git log 拉取范围内的提交。不要用 git log 的分页交互，加 --no-pager 或管道处理。推荐命令（按范围二选一）：

版本区间：

git --no-pager log v2.4.0..v2.5.0 --pretty=format:'%h%x09%an%x09%ad%x09%s' --date=short

时间范围：

git --no-pager log --since='2024-03-01' --until='2024-03-15' --pretty=format:'%h%x09%an%x09%ad%x09%s' --date=short

需要正文（含 BREAKING CHANGE 说明、多行描述）时追加 %x09%b 或分次用 --pretty=format:'%H%n%B%n---'。

辅助命令：

• 列出可用 tag（确认版本区间是否存在）：git --no-pager tag --sort=-creatordate | head -20
• 上一个 tag：git describe --tags --abbrev=0
• 首次提交（无上一 tag 时兜底范围）：git --no-pager log --pretty=format:'%h %ad %s' --date=short
• 统计文件改动辅助判断影响面：git --no-pager log <range> --stat

若范围内无提交或 tag 不存在，明确告知用户并请其确认范围，不要静默产出空文档。

步骤 3：解析与归类

逐条解析 commit subject，优先识别 Conventional Commits 前缀，映射到用户友好的分组：

处理原则：

• 破坏性变更最重要，永远放在最前，说明改了什么、为何、如何迁移。
• 面向终端用户时，chore/refactor/ci/test 等纯工程提交通常不进入正文，或合并成一句"底层稳定性与性能改进"。
• 面向开发者集成方时，API 变更、依赖升级要保留并标注。
• 不带规范前缀的 commit：读 subject 语义自行归类；实在无法判断的归到"其他变更"。
• 合并重复：同一功能的多次提交（wip、fix typo、address review）合并为一条有意义的条目，不逐条罗列。
• 过滤噪音：Merge branch、纯格式化、版本号 bump 等一般剔除。

步骤 4：面向读者改写

这是最关键的一步。把每条选中的 commit 改写成读者视角：

• 讲结果，不讲实现："重构了 X 模块"→"提升了 X 的加载速度"。
• 讲价值：说明这个变更给用户带来什么好处或解决了什么困扰。
• 去术语：终端用户文档避免 middleware、race condition、refactor 等词；开发者文档可保留。
• 动词开头、简洁：每条一句话，句式统一（如统一用"新增/优化/修复"开头）。
• 不确定语义时不编造：若 commit 信息太简略无法判断用户可见影响，保留原意并标注 [待确认：此项面向用户的表述]，请用户核对，不要臆造功能。

步骤 5：组装文档

按目标格式拼装（见下）。破坏性变更置顶，其余按重要性排序（新功能 > 修复 > 改进）。

输出格式约定

标准 changelog / release notes（Markdown）：

# [产品名] [版本号] — [日期或日期范围]

> [可选：一句话概述本次更新亮点]

## ⚠️ 破坏性变更
- [改了什么]。迁移方式：[如何适配]

## ✨ 新功能
- [用户视角的功能描述]

## ⚡ 性能优化
- [优化点]

## 🐛 问题修复
- [修了什么问题]

## 🔧 其他改进
- [底层改进合并描述]

• 遵循 [Keep a Changelog] 惯例：分组标题稳定、条目以动词开头、最新版本在最上。
• 应用商店描述：不用分组标题，写成 150200 字的连贯段落，突出 13 个最重要的新功能，语言生动、避免技术词，末尾可加一句好评引导。
• 空的分组不输出（没有 perf 就不放性能章节）。
• 交付方式：短内容直接贴在对话中；用户要求成文或内容较长时，用 Write 保存为 CHANGELOG.md 或 RELEASE_NOTES.md。若项目已有 CHANGELOG.md，先 Read 读取，把新版本追加到顶部，保留历史条目，不要覆盖。
• 每条可选择性附上 commit 短哈希便于溯源（(a1b2c3d)），面向终端用户时通常省略。

边界

• 只读取，不改写历史：仅执行 git log、git tag、git describe 等只读命令，绝不执行 commit、push、tag、rebase 等修改仓库的操作。
• 不编造变更：文档内容严格来自真实 commit；无法判断的表述标注待确认，不虚构功能或数据。
• 范围为空要报告：区间无提交、tag 不存在、非 git 目录等情况，明确告知并请用户修正，不产出空壳文档。
• 不做版本决策：是否发布、版本号怎么定（semver 判断可给建议）由用户决定。
• 敏感信息：若 commit 信息里出现内部代号、未公开客户名、密钥等，改写时剔除或提示用户。