release-notes-generator

发布说明生成器

根据 Git 提交生成 3 种格式的完整发布说明。

工作流

1. 分析上一个发布标签或指定版本之后的 Git 历史记录
2. 通过 gh api 获取 PR 详情（标题、描述、标签）
3. 将变更分类为新功能、错误修复、改进、安全问题和重大变更
4. 生成 3 种输出：CHANGELOG.md 章节（技术版）、PR 发布正文（半技术版）、Slack 消息（面向用户）
5. 将技术术语转化为通俗语言
6. 检测到数据库迁移时发出提醒

使用方法

基本用法

Generate release notes since last release

Create release notes for version 0.18.0

指定范围

Generate release notes from v0.17.0 to HEAD

仅预览

Preview release notes without writing files

输出格式

1. CHANGELOG.md 章节

面向开发者的技术格式：

## [0.18.0] - 2025-12-08

### Objective
[1-2 sentence summary]

### New Features
#### [Feature Name] (#PR)
- **Description**: ...
- **Impact**: ...

### Bug Fixes
- **[Module]**: Description (#issue, [error-tracker] ISSUE-XX)

### Technical Improvements
#### Performance / UI/UX / Architecture
- [Description]

### Database Migrations
[If applicable]

### Statistics
- PRs: X
- Features: Y
- Bugs: Z

2. PR 发布正文

使用 .github/PULL_REQUEST_TEMPLATE/release.md 中的模板：

• 目标概述
• 附带规格说明链接的新功能
• 附带错误追踪器引用的错误修复
• 按类别列出的改进
• 迁移说明
• 部署清单

3. Slack 公告

使用 .github/COMMUNICATION_TEMPLATE/slack-release.md 中面向产品的格式：

• 包含 PR 链接，便于追溯
• 使用非技术语言
• 聚焦于对用户的影响（终端用户、管理员、利益相关者）
• 使用表情符号，提升可读性
• 汇总统计数据

工作流集成

此技能集成到发布工作流中：

1. Analyze commits: git log <last-tag>..HEAD
2. Determine version number (MAJOR.MINOR.PATCH)
3. Generate 3 outputs
4. Create PR develop -> main with "Release" label
5. Update CHANGELOG.md
6. After merge: create git tag
7. Generate Slack announcement

从技术术语到产品语言的转换

此技能会自动将技术语言转换为通俗表达：

技术表述	产品表述
"N+1 query optimization with DataLoader"	"列表加载速度更快"
"AI embeddings implementation with pgvector"	"新增智能搜索"
"Fix scope permissions in getPermissionScope()"	"修复访问权限错误"
"Migration webpack -> Turbopack"	不对外沟通
"React hooks refactoring"	不对外沟通
"Fix N+1 in user loaders"	"性能改进"
"Add retry logic for DB connection errors"	"连接稳定性更佳"

提交类别

根据约定式提交前缀对提交进行分类：

前缀	类别	是否纳入 Slack？
feat:	新功能	是
fix:	错误修复	是（面向用户时）
perf:	性能	是（简化表述）
security:	安全	是
refactor:	架构	否
chore:	维护	否
docs:	文档	否
test:	测试	否
style:	样式	否

控制台输出格式

生成发布说明时，始终在控制台中显示清晰的摘要，其中包括：

迁移提醒（关键）

如果检测到迁移，请醒目显示：

╔══════════════════════════════════════════════════════════════════╗
║  ⚠️  [WARNING] DATABASE MIGRATIONS REQUIRED                      ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                  ║
║  This release contains X migration(s):                           ║
║                                                                  ║
║  • 20251210123456_add_feature_description                        ║
║  • 20251211094532_update_status_enum                             ║
║                                                                  ║
║  Action required BEFORE deployment:                              ║
║  → Run: [migration-command]                                      ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝

如果没有迁移：

✅ [OK] No database migrations required

检测方法

检查自上次发布以来新增的迁移文件：

# Find new migrations since last tag
git diff <last-tag>..HEAD --name-only -- migrations/

示例

用户：“生成 v0.17.0 以来的发布说明”

输出：

Analyzing commits from v0.17.0 to HEAD...

Found:
- 15 commits
- 8 PRs merged
- 2 new features
- 5 bug fixes
- 3 improvements

╔══════════════════════════════════════════════════════════════════╗
║  ⚠️  [WARNING] DATABASE MIGRATIONS REQUIRED                      ║
╠══════════════════════════════════════════════════════════════════╣
║  This release contains 1 migration(s):                           ║
║  • 20251208143021_add_user_preferences                           ║
║  Action required: [migration-command]                             ║
╚══════════════════════════════════════════════════════════════════╝

--- CHANGELOG.md Section ---
[Technical format output]

--- PR Release Body ---
[Semi-technical format output]

--- Slack Announcement ---
[Product-focused format output]

Write to files? (CHANGELOG.md, clipboard for PR/Slack)

使用的命令

# Get last release tag
git tag --sort=-v:refname | head -n 1

# List commits since tag
git log <tag>..HEAD --oneline --no-merges

# Get PR details
gh api repos/{owner}/{repo}/pulls/{number}

# Get commit details
git show --stat <sha>

提示

• 在仓库根目录运行
• 确保 gh CLI 已通过身份验证
• 发布前检查生成的内容
• 根据受众调整产品语言
• 使用 --preview 可查看输出而不写入文件

参考文件

• assets/changelog-template.md - CHANGELOG 章节模板
• assets/slack-template.md - Slack 公告模板
• references/tech-to-product-mappings.md - 转换规则
• references/commit-categories.md - 分类规则

相关技能

• github-actions-templates - 用于 CI/CD 工作流
• changelog-generator - 原始灵感来源（ComposioHQ）