release-notes

Release Notes Generator

把从上一个 tag 到当前 HEAD（或指定 tag）之间的 git 历史整理成符合 Keep a Changelog 的发版说明。

何时触发

• 用户说："生成 v1.2.0 的 release notes" / "写一下 0.4.0 的 changelog"
• 用户打了新 tag（例如 v0.4.0）后要求写说明
• cron 在 v*.*.* tag 推送后触发

输入

• 必需：目标版本号（形如 v0.4.0 或 0.4.0，自动带/去 v 前缀兼容）
• 可选：上一个 tag（默认用 git describe --tags --abbrev=0 <target>^）

输出

两个文件都要写：

1. CHANGELOG.md：在 ## [Unreleased] 下方插入新条目（不覆盖旧版本）
2. docs/releases/<version>.md：独立的发版公告（便于网站、邮件、微信直接引用）

工作流程

Step 1：预检

# 1.1 必须在 git 仓库里
git rev-parse --show-toplevel

# 1.2 工作区必须干净（有未提交改动时警告，不强制）
git status --porcelain

# 1.3 确认目标版本格式
# 接受 v0.4.0 / 0.4.0；内部统一成 v0.4.0

失败就停下来告诉用户，不要继续生成"碰运气"内容。

Step 2：收集原始数据

# 上一个 tag
PREV=$(git describe --tags --abbrev=0 <target>^ 2>/dev/null || echo "")

# 范围内的 commit 清单（排除 merge commits）
git log ${PREV:+$PREV..}<target> --oneline --no-merges

# 每个 commit 的完整 message（分类需要 body）
git log ${PREV:+$PREV..}<target> --format='%H%n%s%n%b%n---' --no-merges

没有 PREV（第一次发版）时，列全部历史，但限 50 条以内（多了就说"initial release"）。

Step 3：按 Conventional Commits 分类

正则匹配 commit message 首行的前缀：

前缀	CHANGELOG 段	优先级
feat(<scope>): 或 feat:	### Added	1
fix(...)	### Fixed	2
refactor(...)	### Changed	3
perf(...)	### Changed	3
docs(...)	### Documentation	4
chore(...) / test(...) / ci(...)	跳过，除非是 breaking 或 chore: bump version	-
BREAKING CHANGE: 出现在 body	### Breaking（置顶）	0
其他	### Other	5

每条在段内按时间倒序排列。

Step 4：抽取 issue / PR 引用

对每条 commit 扫 body 里的 #(\d+)、(#\d+)、GH-\d+：

# 如果有 gh CLI 且 issue 开着，拿 title 补充上下文
gh issue view <N> --json title,labels -q '.title + " [" + (.labels | map(.name) | join(",")) + "]"'

没 gh CLI 或 issue 404 → 保留 #N 原样引用，不崩。

硬约束：每一个在 commit body 里出现的 #N 引用都必须保留在对应 bullet 末尾，格式 . Refs #N。不能偷懒抽象掉——审查人要靠它回追 issue。如果一条 commit 有多个 #N，全部列出：. Refs #12, #17。