用途
Release Notes Generator 是一个用于为软件发布创建发布说明(release notes)的技能,可汇总新功能、修复和破坏性变更。适用场景包括:为新版本准备发布说明;为用户或利益相关者总结变更;为破坏性变更编写迁移步骤。 需要注意的是,若需维护项目的 CHANGELOG.md 文件,应改用 keep-a-changelog-generator。本技能撰写的是单个版本的叙述性公告,而后者维护的是结构化、累积的变更日志。
主要能力
该技能提供了一套发布说明的结构模板,并给出撰写指南,主要涵盖以下内容板块:
- 亮点(Highlights):用 2-3 句话简要总结最重要的变更,聚焦用户价值——用户现在能做什么以前做不到的事、解决了什么问题、为什么应该升级。
- 新功能(New Features):按功能名称分节,说明其作用、重要性,并附上基本用法示例。
- 改进(Improvements):逐条列出改进项。
- Bug 修复(Bug Fixes):列出修复的问题,并引用 issue 编号(如 #123)。
- 破坏性变更(Breaking Changes):说明变更内容、变更原因、分步迁移指南,并提供前后对比的代码示例。
- 依赖(Dependencies):记录依赖包版本的更新,如 package-name 从 1.0.0 升级到 2.0.0。
使用方式
该技能使用 Git 命令收集信息,包括:
- 自上次发布以来的提交:
git log v1.1.0..HEAD --oneline - 详细提交信息:
git log v1.1.0..HEAD --format="%h %s%n%b%n---" - 变更文件:
git diff v1.1.0..HEAD --stat - 贡献者:
git log v1.1.0..HEAD --format="%an" | sort | uniq
版本号遵循语义化版本规范(semver):
- 主版本号(1.0.0):破坏性变更
- 次版本号(0.1.0):新增功能,向后兼容
- 修订号(0.0.1):Bug 修复,向后兼容
该技能还提供了一个发布说明示例和一份检查清单,清单项目包括:亮点是否总结了关键变更、所有新功能是否附带示例、破坏性变更是否有迁移指南、Bug 修复是否引用 issue 编号、版本号是否遵循 semver。
适用场景
适用于软件项目的版本发布环节,需要面向用户或利益相关者产出叙述性公告时使用。
限制
该技能不用于维护累积的 CHANGELOG.md 文件;官方文档未提供其他功能、收费、价格、平台或效果方面的信息。