值得团队真正长期坚持采用的发布说明最佳实践
阅读约 1 分钟 更新于
真正重要的发布说明最佳实践，都是带有明确后果的：在合并代码时就写好条目，说明谁会受到影响，即使不需要任何操作也要明确说出来，为破坏性变更标注日期，每个变化只保留一条永久条目，按结果分组，并且保留那个无趣的部分。这些做法每一条都会改变读者的实际行为。这个主题上的大多数其他建议，改变的只是说明看起来的样子。
搜索发布说明最佳实践，得到的多半是写作风格上的建议：写得清楚一点，简洁一点，用平实的语言，加一些截图。这些建议没有一条是错的，但也没有一条真正改变了什么，因为从来没有哪个团队坐下来是打算把话写得含糊不清的。下面这些做法，每一条都附带了跳过它会付出的代价，因为一个没有失败场景的做法，充其量只是个人偏好。
| 做法 | 跳过它的代价 |
|---|---|
| 在合并时写条目，而不是在发布时 | 之后再重构的条目只会写”若干改进” |
| 明确点名谁受影响 | 每个读者都会认定这与自己无关 |
| 说明必需的操作，包括”无需操作” | 收到四十张一模一样的支持工单，读者会假设最坏的情况 |
| 给破坏性变更标注日期，而不是版本号 | 截止日期过去之后才被发现 |
| 每个变化保留一条永久、可链接的条目 | 没人能回答”这是什么时候变的” |
| 按结果分组，而不是按系统分组 | 读者需要了解你的架构才能找到相关部分 |
| 保留那个无趣的部分 | 安全团队、合规审查员和排查版本不一致问题的人都会失去唯一的信息来源 |
发布说明的最佳实践有哪些
在合并代码时写条目，而不是在发布时。 跳过的代价：从提交历史重构发布内容的人，并不是做出这个改动的人，他只能猜测意图。两周后才补写的条目，通常都只会写”若干改进”。
明确点名谁受影响。 “使用 Business 套餐的团队”、“任何使用 v1 导出 API 的人”、“在 Postgres 14 上自托管的安装”。跳过的代价：每个读者都得自己判断是否与自己有关，而大多数人会认定无关。
说明必需的操作，即便是”无需操作”也要说出来。 跳过的代价：支持团队要把同一个问题回答四十遍，而没有主动询问的读者只会假设需要做点什么，然后一拖再拖。
为破坏性变更标注日期，而不是发布版本号。 “在 v5 中移除”对不清楚 v5 何时发布的人毫无意义。“11 月 1 日起停止工作”是一个人人都能放进日历里的日期。跳过的代价：截止日期过去之后才被发现。什么才算破坏性变更，以及发布它的检查清单，都在什么是破坏性变更一文中。
每个变化只保留一条永久、可链接的条目。 一封邮件不是档案，一条 Slack 消息也不是参考资料。跳过的代价：六个月后没人能回答”这是什么时候变的”，包括你自己。邮件依然有它自己的职责，产品更新邮件模板一文对此有详细说明，它指向那条记录，而不是取代它。
按结果分组，而不是按系统分组。 跳过的代价：读者必须把你的系统架构记在脑子里，才能弄清楚哪部分和自己有关。由此而来的排序方式，在如何写发布说明一文中。
保留那个无趣的部分。 依赖升级和内部变更依然留在最后，每项一行。跳过的代价：安全团队、合规审查员，以及排查版本不一致问题的人，都会失去他们唯一的信息来源。最容易在这方面出错的是修复类条目；缺陷修复发布说明介绍了怎样写，才能让读者知道是否需要采取行动。
体验日志的最佳实践是什么，它和发布说明有何不同
体验日志是一份参考资料，因此它的实践关注的是完整性和结构，而不是说服力。四条真正重要的是：
- 每一行固定一种条目类型。 Added、Changed、Deprecated、Removed、Fixed、Security。这不是风格规范，而是一个过滤器：它让人能够要求”只看破坏性变更”。Keep a Changelog 这个惯例通常就是这套分类的来源。
- 一个未发布部分。 用来存放合并之后、发布之前的条目。它的缺失正是团队总是拖到最后才补写条目的原因。
- ISO 日期格式。 用
2026-08-28，而不是28/08/26，后者在不同读者眼里会变成两个不同的日期。 - 每个变化一条条目，而不是每次提交一条。 三次修复同一个 bug 的提交，应该只算一条条目。
这两种成果物在体验日志与发布说明一文中有更完整的比较；简单说就是，体验日志的实践守护的是完整性，发布说明的实践守护的是读者的注意力。 专门面向企业客户来撰写的这份私有发布说明讲的 是这件事的另一个版本，它只有当你的客户不再全都用着同一个构建版本时才会浮现出来：同样是守 护完整性和注意力这两个目标，只是要按账户分别校准，而不是一次性广播给所有人。
三个盲目跟风的误区
用表情符号作为条目类型。 一个火箭图标和一个扳手图标构不成分类体系。它们看起来整齐，却无法被过滤、排序，也无法被屏幕阅读器有效读出。用文字来表达，如果确实想加表情符号，就把它放在文字后面。
用语义化版本号作为托管产品的标题。 语义化版本控制是关于 API 兼容性的一种承诺。对于一个没人自己选版本的 SaaS 产品来说，标题里的版本号只是把内部归档信息打扮成新闻。把语义化版本留在体验日志里，不要放进发布公告。
不论内容如何都按固定时间表发布。 内容空洞的月度说明，只会教会人们把你的说明当成噪音。有话可说的时候再发布，其余的交给体验日志去记录。
唯一真正困难的那件事
在不把内容写两遍的前提下，让体验日志和发布公告保持同步。
大多数团队一开始都从一个页面起步，等到读者群体开始分化时才把它拆开，然后悄悄放任其中一个腐坏，通常是体验日志，因为它是那个没有截止日期压着的。走出困境的办法在于结构，而不是自律：把条目当作带有类型、日期和目标读者的数据来维护，把两个展示面都当成这份数据的渲染结果。我们的体验日志工具汇总涵盖了这方面的现有选择，包括我们的竞争对手，而Beamer 替代方案页面则是与大多数团队最初使用的那款小组件的诚实对比。
发布说明模板就是条目已经存在之后，挑选这一步真正发生的地方。
如果只能采纳一件事
在合并代码时，以固定格式，带上类型，把条目写下来。这个页面上的其他每一条实践，一旦这一点落实了都会变得容易，而离开它，没有一条能够真正生效。
FAQ
发布说明应该配截图吗? 只应该配上实际改变的东西正在被使用的截图。没人访问过的设置页面截图只会增加滚动长度，不会增加信息量。一段说清结果和受影响读者的文字，胜过一张两者都没说清的图片。
破坏性变更的发布说明应该怎么写? 先写日期，其次是受影响的调用方，再是必需的操作，最后是迁移方法。绝不要以版本号开头。完整的格式连同示例条目，都在什么是破坏性变更一文中。
发布说明应该由工程团队来写，还是由市场团队来写? 由做出这个改动的工程师在合并代码时起草，再由把它当成陌生人来阅读的人来编辑。单靠任何一方都写不出客户能够据以行动的说明。
理想的发布说明格式是什么样的? 先写有截止日期的事项，再写新功能，然后是改进，最后是每项一行的其余内容列表。发布说明模板就是这种格式做成的一份填空页面。
本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。