发布说明示例：针对每一种变更类型的写法，以及为什么有效
阅读约 1 分钟
最好的发布说明示例都很简短，会点明谁受到影响，并说清楚下一步该做什么。下面为你将要发布的每一种变更类型各给出一个示例，并解释它为什么有效，这样你就可以照搬它的形状，换上自己的事实。
所有示例都是虚构的，背景是一个名叫 Tidepool 的虚构开票应用。
好的发布说明示例有哪些共同点？
它们用用户自己的话，告诉用户发生了什么变化，以及他们（如果需要的话）该做什么。每种变更类型承担的任务不同，所以形状也随之变化。
| 变更类型 | 条目必须说明 | 放在哪里 |
|---|---|---|
| 新功能 | 读者现在能做什么，以及谁能用到 | 发布说明的最上方 |
| 改进 | 什么变得更快或更容易，有数字就写上数字 | 功能之后 |
| 缺陷修复 | 读者看到的症状，以及它已经修好 | 改进之后 |
| 破坏性变更 | 谁受影响、日期、迁移方法 | 永远放在最前面 |
| 安全修复 | 暴露了什么、是否被利用、该怎么做 | 最前面 |
| 弃用 | 什么将被移除、截止日期、替代方案 | 靠近顶部 |
| 应用商店说明 | 每项变更一句平实的话，不超过字数限制 | 商店页面 |
| 内部说明 | 变化了什么，以及该如何向客户说明 | 支持和销售渠道 |
好的新功能说明是什么样的？
好的功能说明，开头就写读者现在能做什么，并点明哪些套餐或角色可以使用。它会跳过实现细节。
用客户的语言发送发票。 你现在可以为每位客户选择一种语言，他们的发票、提醒和付款页面都会随之切换。法语、德语、西班牙语和葡萄牙语适用于所有套餐。请在客户页面的”账单偏好”下进行设置。
标题是读者会大声说出来的一句话，正文则给出范围和位置。只扫一眼加粗那一行的读者，也知道发布了什么。更完整的方法见如何写出用户真正愿意花时间读完的发布说明。
好的改进说明是什么样的？
改进说明描述的是读者能感受到的变化，如果有实测的数字，就把数字写上去。没有数字的话，就说明读者不用再做什么了。
发票列表的加载速度提升了约三倍。 发票超过 5000 张的账户，以前要等大约九秒才能看到列表，现在大约三秒就能打开。无需任何操作。
“性能改进”什么也没告诉读者，而九秒对三秒，是他们周一早上就能自己验证的说法。结尾的”无需任何操作”，回答了每位读者都会有的那个问题。
好的缺陷修复说明是什么样的？
缺陷修复说明描述的是用户看到的症状，而不是代码里的原因，并且说明他们是否需要重做什么。没有人注意到的修复，可以放在底部的列表里。
已修复：提醒邮件在到期日被发送了两次。 如果发票的到期日恰好是某个月的最后一天，部分客户会收到两封一模一样的提醒。该问题已修复。已经发出的提醒不受影响，也无需任何人重新发送。
标题以”已修复”开头，浏览的人一眼就能分类，而真正的触发条件（月底最后一天）紧随其后。
如何为破坏性变更撰写发布说明？
破坏性变更的说明，先写日期和受影响的人群，再在同一条目里给出迁移方法。它在发布说明里排在最前面，因为这是读者绝不能错过的那一条。
自 2026 年 12 月 1 日起，Webhook 签名将成为必需项。 从这一天起，Tidepool 将不再发送未签名的 webhook 负载。这会影响所有接收 webhook 却不检查
Tidepool-Signature请求头的用户。迁移方法：使用”设置，开发者”下的密钥来验证该请求头。如果你已经在验证签名，则无需任何操作。
日期写在标题里，所以即使只是扫读也不会错过。受影响的人群是按他们的行为来界定的，而最后一句话让已经没问题的人放了心，这样就减轻了支持的负担。关于如何判断一项变更是否算数，破坏性变更这篇指南里有详细说明。
安全修复的说明是什么样的？
安全说明要写清楚暴露了什么、是否有人利用过、谁受影响，以及他们必须做什么。保持客观和冷静。
安全：密码重置链接可能被重复使用。 在 2026 年 9 月 3 日至 17 日期间，密码重置链接在使用过一次之后仍然保持有效。我们没有发现任何迹象表明它被利用过。该问题已修复，所有尚未使用的重置链接都已失效。如果你在这段时间内申请过重置，请重新申请一个新的链接。
确切的时间窗口让读者能够判断自己的暴露程度，而关于是否被利用的那句话，回答了每个人首先会问的问题。“一个潜在的问题”读起来像是在隐瞒，所以把你知道的如实写出来。
如何撰写弃用通知？
弃用通知要说明什么将被移除，给出一个确定的截止日期，并指向替代方案。
v1 发票接口已弃用，将于 2027 年 3 月 1 日终止。
GET /v1/invoices会继续工作到 2027 年 3 月 1 日，之后将返回410 Gone。请改用GET /v2/invoices，它返回相同的字段，另外多了currency。现在 v1 的响应会附带一个包含截止日期的Sunset响应头。文档中有一份并排对照的迁移指南。
接口名称写在标题里，因为受影响的人会去搜索它，而替代方案就放在移除说明的旁边。Sunset 响应头会告诉开发者，哪些调用仍在使用旧版本。更完整的论述见弃用 API。
应用商店的发布说明是什么样的？
应用商店说明是两三句平实的话，因为大多数人只会读第一行。开头写用户能注意到的那项变更。
扫描一张纸质收据，Tidepool 会自动填好金额、日期和商家。深色模式现在会跟随你手机的设置。我们还修复了从通知打开发票时发生的崩溃。
最有用的变更放在最前面，而修复则点明了发生崩溃的场景。没有版本号，也没有”错误修复与改进”这种话。移动应用的发布说明介绍了各个商店专有的规则。
内部发布说明应该包含什么？
内部说明是写给支持和销售的版本。它补上公开说明里省略的内容：该怎么说，以及不要承诺什么。
多语言发票今天上线（所有套餐）。 支持团队：客户在”账单偏好”下设置语言，已有的发票会保留原来的语言。意大利语暂不可用。销售团队：这项功能向所有套餐开放，所以不要把它当作升级卖点来宣传。
每类受众都有自己带标签的一行，而这条说明在客户开口询问之前，就划清了边界（“意大利语暂不可用”）。内部发布说明一文介绍了格式和渠道。
一条糟糕的发布说明改写之后是什么样的？
糟糕的发布说明列出的是团队做了什么，而不是读者得到了什么。修正的办法是把结果挪到前面，并删掉内部术语。
修改前：
v3.8.1 重构了提醒调度器。修复了
ReminderJob中的竞态条件。将bull更新到 4.12。其他改进。
修改后：
提醒邮件不会再发送两次。 如果发票的到期日恰好是某个月的最后一天，客户可能会收到两封提醒。该问题已修复，已经发出的提醒不需要重新发送。无需任何操作。
3.8.1 中还包括：
bull已更新到 4.12。
依赖升级被降到了页脚的一行，而竞态条件则变成了客户能认出来的症状。
如何让各个版本的发布说明保持一致？
在变更合并时就起草每一条，并让一个人在发布之前批准它。
Changeloop 就是这样工作的：它用 AI 从每个已合并的 pull request 起草一条条目，并把它留给人来批准。批准这一步，正是编辑应用上述规则的地方。如果想先确定格式，可以从发布说明模板开始，已完成的页面是什么样子，请参阅体验日志示例。
FAQ
什么是新的发布说明? 新的发布说明，就是随产品最新版本一起发布的那条消息，描述发生了什么变化以及用户需要做什么。它涵盖功能、改进、修复和破坏性变更。
发布说明和体验日志有什么区别? 体验日志什么都记，留给想看完整历史的人。发布说明则从中挑选：只讲一次发布，写给要判断它与自己是否相关的读者。更完整的对比见体验日志与发布说明的区别。
发布说明是什么意思? 发布说明告诉用户一次发布改了什么。这个词涵盖任何解释发布了什么的简短文档，从应用商店里的”新功能”文字，到公司网站上的一个页面。
每条发布说明应该写多长? 大多数条目写两到四句话就够了：结果、谁受影响，以及该做什么。破坏性变更或安全修复可能会更长一些，因为它需要日期或迁移方法。
本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。