发布说明模板

模板

方括号中的内容都是占位符。其余内容都值得保留，包括顺序：用户会寻找与自己相关的内容，因此破坏性变更排在最前面，而内部工作则完全不出现。

## [产品] [版本] - [日期]

[一句话说明本次发布的目的。日常发布可省略。]

### 破坏性变更
- [什么坏了、应改用什么，以及截止日期。附上迁移步骤链接。]

### 新增
- [以结果描述的能力。写“固定一个筛选条件并复用”，
  而不是“新增 SavedView 模型”。]

### 改进
- [什么变得更快、更清晰或更可靠，以及大致提升幅度。]

### 修复
- [用户看到的症状，而不是代码中的原因。]

如果某个部分为空，请删除该标题。空的“修复”部分读起来就像什么都没修复一样，而下面没有任何内容的标题会让读者以为页面没有加载完整。

同一份模板，填写后的样子

填入真实内容后就是这样。请注意，没有任何条目提到文件、分支、工单编号或人名，而破坏性变更的开头就是读者需要采取的行动。

## Acme API 4.2 - 2026 年 8 月 20 日

所有列表端点的分页现在改为基于游标。

### 破坏性变更
- 所有列表端点已移除 `?page=`。请使用上一次响应中的
  `nextCursor` 值。2026 年 10 月 1 日之后，`?page=` 将返回
  400。迁移步骤：acme.example/docs/pagination

### 新增
- 收件箱中的已保存视图。固定一次筛选条件，即可从侧边栏
  重复使用。
- 现在可以将 webhook 限定到单个项目。

### 改进
- 列表端点在大型账户上的响应速度提升了约四倍。
- 导出任务现在会报告进度，而不是看起来像卡住了。

### 修复
- 被邀请的成员在首次登录前不会再看到空白的仪表盘。
- 导出中的时间戳现在会遵循账户所在的时区。

每个部分应包含什么

破坏性变更

唯一一个包含截止日期的部分。说明什么将停止工作、应改用什么，以及停止工作的日期。如果你还没确定日期，先不要发布这部分：没有日期的破坏性变更会被读作紧急事项，而一连串虚假的紧急信息，正是人们学会忽略你发布说明的方式。

新增

描述结果，而不是你构建的对象。判断标准是：这一行对从未见过你代码的人来说是否仍然有意义。“收件箱中的已保存视图”能通过检验。“新增 SavedView 模型及其迁移”则不能。

改进

在能够诚实做到的地方给出量化数据。“更快了”几乎没有价值，读者会自动打折扣；而“在大型账户上快了约四倍”值得一读，并且设立了一个可以被追责的预期。如果无法测量，就用一种可被证伪的方式说明哪里更好了。

修复

写症状，而不是原因。用户在这些说明中寻找的是发生在他们身上的事情，因此“被邀请的成员会看到空白的仪表盘”是可以被搜到的，而“修复了成员资格缓存中的一个竞态条件”则不是。

变体

这四个部分适用于大多数发布。有三种情况需要调整：

• 移动应用发布。应用商店会显示一个简短的“新变化”字段，因此先用一句话开头，让它能在商店列表中被读到，再链接到完整说明。商店审核也可能让某个构建版本延迟数天上线，因此应按发布日期而不是合并日期来标注说明的日期。
• API 发布。像给 API 打版本号一样给说明打版本号，并将弃用窗口直接写在说明本身，而不只是写在文档里。API 使用者阅读说明正是为了准确了解自己还剩多少时间。
• 内部或管理工具。去掉“改进”部分，将其并入“修复”。内部用户关心的是自己的工作流程是否发生了变化，而冗长的“改进”部分会把这一点埋没。

保持可读性的四条规则

1. 为不了解你代码的人而写。不要出现文件名、分支名、工单 ID、服务名称或内部代号。
2. 省略所有对用户没有可见影响的内容。依赖更新、重构、CI 变更和拼写修正应该属于提交历史，而不是发布说明。发布说明最常见的失败方式，就是被团队之外没人能看到的工作内容填满。
3. 一条条目，一项变更。如果一行需要用到两次“和”，那很可能应该拆成两条条目。
4. 以人们可以依赖的节奏发布，即使这个节奏是“每次发布时才写”。一周内出现四次、之后又两个月没有动静的说明，会被当作噪音对待。

发布说明的格式：按顺序排列的各个部分

格式的重要性不如顺序。无论你使用什么标题样式，浏览发布说明的读者都希望以相同的顺序获得同样的四类信息，而每一种流行的发布说明格式都只是这一顺序的变体。

1. 标题应说明对读者而言发生了什么变化，而不是版本号。版本号放在下方一行较小的文字中，日期采用 ISO 格式（2026-08-29），以便在任何语言环境下读起来都一样。
2. 破坏性变更以及任何有截止日期的内容排在最前，即使内容很小。如果读者只读一段就停下来，这应该是他们需要的那一段。
3. 新增内容，每段一项，第一句话给出结果，并且每次都明确说明所需的操作，包括“无需操作”。
4. 修复和改进，之后是底部的一份单行列表，列出其余所有内容。依赖更新和内部变更会保留下来，因为唯一会去搜索它们的那个人确实需要它们。

在 Markdown 中，这是一个 H2 标题、一行淡化处理的版本和日期，然后是“破坏性变更”“新增”“改进”“修复”的 H3 小节。在邮件中，顺序相同，标题作为邮件主题。在 changelog widget 中，则是标题和第一段，其余内容放在链接之后。上面的模板就是这种结构的完整书写形式。

关于写作本身而非结构，请参阅博客上的如何撰写人们真正会阅读的发布说明和值得坚持的发布说明最佳实践。

常见问题

发布说明应该多长？

只需长到能涵盖影响用户的变更，不必更长。只有一个 bug 修复的发布，两行就够了。为了让小型发布看起来更重要而刻意填充内容，会训练人们跳过那些真正重要的发布。

发布说明和 changelog 有什么区别？

实际上这两个术语常被交替使用。在有团队区分它们的场合，发布说明描述单次发布并且是写给用户看的，而 changelog 则是随时间推移的所有发布的持续列表。本模板涵盖的是一次发布；而 changelog 就是把这些说明按最新到最旧堆叠起来所得到的结果。

发布说明应该有版本号吗？

只有在用户能看到版本号的情况下才需要。版本号对 API、库和已安装的软件很有用，因为读者需要知道自己使用的是哪个版本。而对于持续部署的 Web 应用，日期更有用，因为那是用户能够与自己的实际体验进行对照的信息。

应该由谁来写？

由了解发生了什么变化的人来写，这通常意味着合并该变更的工程师，再由掌握文案语气的人来编辑。完全交给一个不参与该项工作的人来写，最常见的失败方式就是说明描述的是工单，而不是变更本身。