release-notes · 发布说明生成器

对比两个 ref，生成结构化的发布说明——用户版（亮点摘要）和开发者版（完整 changelog）。

流程

1. 确定对比范围

• 用户指定两个 ref → 直接用
• 仅指定一个 → base 为上一个 tag，head 为给定 ref
• 都没指定 → 用最近两个 tag；无 tag 则用 main/master vs HEAD
• 询问确认后再继续

2. 收集变更

git log <base>..<head> --oneline --no-merges --format="%h %s (%an)"
git diff --stat <base>..<head>
git shortlog -sn <base>..<head>   # 贡献者

3. 分类规则

按 Conventional Commits 分类。非标准 commit 从语义推断：

4. 生成两种版本

用户版（Release Highlights）——给用户看的，非技术语言：

## v1.5.0 (2026-08-10)

### 🚀 新功能
- 文件上传速度提升 3 倍
- 支持批量管理标签

### 🐛 修复
- Safari 浏览器下无法粘贴图片 [已修复]
- 导出 CSV 时中文标题乱码 [已修复]

### ⚠️ 不兼容变更
- API 接口 `/v1/items` 返回格式变更，详见迁移指南

开发者版（Full Changelog）——完整变更记录：

## [1.5.0] - 2026-08-10

### 🚀 Features
- `feat:` file upload: parallel chunked upload (#234) [`abc1234`](link) @author
- ...

### 🐛 Bug Fixes
- `fix:` paste event not firing in Safari (#245) [`def5678`](link) @author
- ...

### ⚠️ Breaking Changes
- `GET /v1/items` 返回格式从 `{data, meta}` 改为 `{items, pagination}`，旧客户端需升级

### 📊 Stats
- **38** commits · **12** files changed · **+1,420** −**386** lines
- **4** contributors: @alice (15), @bob (12), @charlie (8), @dave (3)

5. 原则

• 两种受众，两种写法：用户版去技术术语，开发者版保留 commit hash 和 PR 链接
• 合并同类：同一个功能的多个 commit 合并为一条描述，不做逐条罗列
• 破坏性变更红标：BREAKING CHANGE 必须醒目标识，附迁移说明（如有）
• 不编造：只从 commit message 和 diff 提取，不猜测意图
• 关联溯源：有 issue/PR 编号的自动补链接（GitHub/GitLab URL）
• 版本号推断：从 tag 推断，无 tag 时建议 v<major>.<minor>.<patch>，询问确认

6. 可选选项

• --single：只生成用户版
• --since <tag>：从指定 tag 到现在
• --format json：输出 JSON 供 CI 消费