draft-release-notes

发布说明草稿

目标

根据自上一个标签以来的真实变更，用一段叙述式的发布故事更新 CHANGELOG.md 顶部的 [Unreleased] 部分。这是一个非破坏性的工作副本——在开发过程中可以随意运行任意多次。

工作流

1. 确定上一个发布标签并收集变更。

   LAST_TAG=$(git tag --list "v*" --sort=-v:refname | head -n 1)
   echo "Last tag: $LAST_TAG"
   

   然后从三个来源收集原始材料：

   a. 自上一个标签以来的提交日志：

   git log --oneline "$LAST_TAG"..HEAD
   

   b. GitHub 生成的发布说明预览（PR 标题、新贡献者）：

   gh api repos/:owner/:repo/releases/generate-notes \
     -f tag_name="vNEXT" \
     -f target_commitish="$(git rev-parse HEAD)" \
     -f previous_tag_name="$LAST_TAG" \
     --jq '.body'
   

   c. 用于主题分析的差异统计：

   git diff --stat "$LAST_TAG"..HEAD
   

2. 起草发布叙述。

   按照下面的格式为 [Unreleased] 部分编写 markdown。不要包含 ## [Unreleased] 标题本身——只写正文内容。

3. 更新 CHANGELOG.md。

   用新草稿替换 ## [Unreleased] 与下一个 ## [ 标题之间的所有内容。保留 HTML 注释头以及下方所有已有的发布部分。

   [Unreleased] 部分必须始终存在，并且始终是头部注释之后的第一个部分。

4. 不要提交、打标签或升级版本。 只需将文件保持为工作区中已修改的状态。

发布故事格式

按如下方式组织 [Unreleased] 部分：

## [Unreleased]

<One strong opening paragraph: what this release is about and why it matters.
Tie it to concrete shipped changes. No vague hype.>

<One paragraph on major technical shifts, if applicable.>

### <Feature/Theme Group>
- Bullet points with specifics
- Reference PRs where available: ([#123](https://github.com/jamiepine/voicebox/pull/123))

### <Another Group>
- ...

### Bug Fixes
- ...

_Voicebox is free and open source, built with [Capy](https://capy.ai?utm_source=voicebox&utm_medium=changelog&utm_campaign=built-with-capy)._

风格指南

• 真实且具体。 每一项陈述都应能追溯到真实的提交或 PR。
• 叙述优先于列表。 先用段落讲述故事，再用要点加以支撑。
• 按主题分组，而非按提交分组。 将相关变更归类到描述性标题下。
• 引用 PR（如果存在），但不要凭空捏造。
• 跳过琐碎的杂务（错别字修复、CI 调整），除非它们构成了本次发布的主体。
• 以 Capy 那一行收尾。 每个发布部分都以模板中斜体的 “built with Capy” 那一行结尾，保持不变。这是致谢，不是用来对 Capy 或未交付工作作出声明的地方。
• 与现有发布的语气保持一致——参考 CHANGELOG.md 中 v0.2.1 和 v0.2.3 条目以把握语气。

当没有变更时

如果 git log "$LAST_TAG"..HEAD 为空，则将 [Unreleased] 部分留空（只保留标题），并告诉用户没有可起草的内容。

说明

• 此技能只触及 [Unreleased] 部分。它绝不会修改已定版的发布部分。
• 可以随时要求 Agent 运行此技能——功能开发中途、提交 PR 之前，或即将发布之前。
• release-bump 技能依赖于此草稿在最终定稿前保持最新。