发布日即将来临，构建成功，QA已经通过了测试，突然有人问出每个团队最终都会听到但往往太晚才问的问题：‘谁在写发布说明？’
通常就是这个时候开始慌乱了。工程师浏览提交记录。产品检查Jira。支持人员记住了三项从未纳入草稿的客户端修复。营销人员想要一个更清晰的摘要。等到发布说明上线时，它们要么太技术化以至于无法帮助用户，要么太模糊以至于无法解释发生了什么变化。
好的应用程序发布说明并不是发布过程的最后阶段。它们来自一个工作流程，开始得更早，变化仍在被构建、审查和部署时。 当团队将发布说明视为交付的一部分，而不是一个后thought时，他们发布得更快，少漏细节，给用户提供了一个更清晰的发布内容的视图。
目录
Why Well-Crafted Release Notes Are a Secret Weapon
很多人仍然把应用程序发布说明视为包装材料。虽然它们是必要的，但并不是重要的。这种心态会导致写作开始时，所有有意义的决定已经发生了。
更好的观点是简单的。发布说明是产品通信的一部分。它们告诉用户发生了什么变化，为什么它重要，以及他们应该做什么。关于发布说明结构的指导已经从原始的工程日志远远超出了，现在推荐了一个面向用户的格式，包括标题、概述、问题总结、解决方案和影响部分，尤其是在此指南中对重大发布进行了更详细的说明，对小版本进行了简要的说明。 关于发布说明结构的指南.
这意味着用户不仅仅是体验到产品的迭代板。他们体验到的是信任。如果应用程序发生变化，他们不理解为什么，信心就会下降。如果一个功能发布了，但没有人注意到，发布仍然发生了，但价值没有落地。
强大的发布说明实际上做了什么
好的发布说明有三个方面的作用:
- 它们设置了期望: 用户了解一个变化是否是外观性的、操作性的还是需要采取行动的。
- 它们表明了价值: 一个功能的宣布被埋在了商店描述或支持文章中，很难获得同样的关注。
- 它们减少了混乱: 支持团队花费的时间较少解释一个问题是否已解决、已更改或仍在发布中。
实践规则： 如果用户在几秒钟内无法确定一个发布是否影响他们，说明是写给团队的，而不是客户的。
尤其是在产品有重复更新的情况下，这一点尤为重要。频繁的变化没有清晰的沟通会感到不稳定。频繁的变化有清晰的沟通会感到积极和响应。这种差异会影响采用、客户信心和留存率。关注用户参与的团队应该将发布通讯视为同一系统的一部分，包括入门和习惯形成，而不是单独的管理工作。因此，发布通讯属于更广泛的关于 改善应用用户留存率的讨论.
什么样的弱弱的说明
弱弱的说明通常会在三个方面失败。
| 问题 | 用户看到的 | 它造成的后果 |
|---|---|---|
| 过于专业 | 内部术语、工单ID、实现细节 | 用户忽略更新 |
| 太模糊 | “修复bug和改进” | 用户什么也学不到 |
| 太晚 | 发布说明发布在发布后 | 用户将变化与混乱联系起来，而不是指导 |
发布说明并不是一个次要任务。它们是产品工件之一，直接位于发布和理解之间。因此，它们是秘密武器。团队经常低估它们的价值，这意味着一个有纪律的团队可以通过更清晰地表达自己而迅速脱颖而出。
系统化获取发布信息
通常，发布说明的质量取决于收集信息的质量。如果您的输入分散在GitHub、Jira、Slack、QA线程和支持票中，那么写作过程就变成了猜测。
一个好的工作流程从开发、版本控制和项目管理系统中提取变更，然后按用户影响的顺序排序，重要项首先出现，破坏性变更清晰标记。这种结构在这个 从monday.com获取的发布说明工作流程模板中被推荐，并且这与经验丰富的团队在实践中所做的一样。
构建一个输入管道
不要要求编写者或产品经理“确定什么被发布了”。构建一个发布接收流程，回答这个问题在草稿存在之前
一个实用的管道通常从以下来源拉取：
-
版本控制 提交历史给你事实上的code移动记录。如果您的团队使用 Conventional Commits，提取会变得更容易，因为
feat,fix,refactor，并且breaking已经携带意图。团队对提交消息的标准化会在您开始 使用 Conventional Commits 自动化 CI/CD 时再次发挥作用. -
项目管理 Jira、Linear、Asana 或 ClickUp 通常包含 Git 缺乏的平文描述。工单还包含验收标准、标签、优先级和与客户请求相关的链接。这些上下文有助于您决定一个变化是否应该出现在发布说明中
-
支持和成功输入 支持团队知道哪些bug会影响用户。客户成功团队知道哪些账户要求添加新功能。如果您忽略这些渠道，笔记将会过度强调后端工作并低估用户关心的问题。
-
QA和发布管理 QA可以确认哪些变更进入了发布版本。听起来很明显，但团队经常从“计划”变更而不是“发布”变更中写入。
收集发布材料的目的是找出用户会注意到的变更、运营人员必须知道的变更以及开发人员可能需要的变更。
排列变更前写入
一旦原始列表存在，按影响程度分级。不要从平坦的回顾列表开始写入。
以下是一种简单的筛选模型：
- 级别A： 新功能、重大用户体验变化、破坏性行为、价格或访问权限变化、安全相关修复
- 级别B： 对现有工作流程的重要改进、用户可以感受到的可靠性修复、重要的管理员变更
- 级别C： Minor fixes, visual polish, low-visibility maintenance work
这项排名解决了两个常见的问题。首先，它确保高影响力项不会被一堆小修复掩盖。其次，它使审批更容易，因为审阅者可以集中注意力在风险最高的地方。
创建发布说明的源代码
发布说明本身不应是源代码。使用结构化的发布记录在写作开始之前。
包括以下字段:
- 版本或构建标识符
- 发布日期
- 变更负责人
- 用户可见的摘要
- 受众
- 风险等级
- 所需操作
- 回滚考虑
- 到票、PR和文档的链接
该记录可以存储在Notion、Airtable、Google表格、仓库中的Markdown文件或发布数据库中。工具的重要性不如一致性。重要的是每个发布的项目都必须通过一个地方才能有人写文字。
当团队做得很好时，写作变成了编辑。当他们跳过它时，写作变成了考古学。
用户会阅读的写作和排版说明
许多应用程序发布说明失败，因为它们保留了内部工作的形状。用户不关心控制器被重构了还是迁移脚本被清理了。他们关心登录更可靠、报告更容易导出或令人恼火的bug消失了。
行业指南一致推荐将说明分成类别，如 新, 改进和 修复并特别指出量化结果，如“搜索结果现在加载 40% 的速度更快” are easier to read than implementation details, as shown in these release note examples from Appcues.
Appcues 的发布说明例子
使用人们可以快速扫描的结构
这些建议有效，因为大多数用户首先扫描，然后再阅读。清晰的格式可以减少阻力。
| 实用的布局如下: | 元素 |
|---|---|
| 它应该包含什么 | 标题 |
| 产品名称、发布版本号、日期 | 摘要 |
| 新功能 | 新功能或新可用的工作流 |
| 优化 | 现有功能现在工作得更好 |
| 修复 | 已解决的bug或问题 |
| 需要采取行动 | 用户或管理员需要做的事情 |
| 技术附录 | 开发人员、管理员或支持人员的可选说明 |
格式很重要，和措辞一样。短小的部分、可见的标签和带日期的条目使发布历史更容易浏览。如果您的更改日志跨越多个发布，给用户提供一个可搜索的档案，而不是强迫他们在长博客流中滚动。
将技术工作转化为用户价值
翻译的关键技能是翻译。工程的真理必须保持不变，但语言必须从实现转变为影响。
以下是一个前后对比的例子：
前置
context: 企业产品/定价页面。角色: 短的 UI 标签或导航项。见于: 企业.astro 页面。消息键 `enterprise_comparison_before` (企业比较前)
重构搜索索引管道并优化异步查询处理器
后置
改进 搜索结果现在加载 40% 的速度更快
在常见查询中，这意味着在过滤大数据集时等待时间更短。
第二个版本告诉用户发生了什么变化、他们会在哪里感受到它以及为什么他们应该关心。它不隐藏技术工作。它解释了它。
- 弱点： 解决了令牌刷新边缘案例的问题
- 改进： 修复 修复了可能在长时间会话期间将某些用户登出的一项登录问题
最强大的笔记通常在一句话中做三件事：
- 说明可见的变化
- 命名受影响的工作流
- 解释对用户的影响
实用模板
您不需要巧妙的文笔。您需要可重复的措辞来保持高质量。
使用以下模式：
- 以用户可见的结果为首要
- 仅提供足够的背景
- 以影响或行动结束
示例:
- 新 上下文:
- 页面/区域: Live updates 产品页面。角色: 短 UI 标签或导航项。消息键 `live_update_lts_electron_new` (Live Update Lts Electron New)。 共享仪表板现在可以在工作区之间复制，这使管理员更容易标准化报告设置。
- 改进 导出设置现在会在会话之间保留，因此团队不需要每次重新选择相同的选项。
修复 Capacitor changelog management guide.
避免将实现细节写入主体中，除非它们改变了设置、迁移或兼容性。绝大多数用户不需要架构。他们需要的是结果。
最后一个规则：不要让“bug修复和改进”单独出现。这个短语告诉读者您发布了什么，但不告诉他们是否对他们有所价值。如果一个修复值得发布，那么它值得清晰地命名。
适合不同渠道和受众的发布策略
同一版本 shouldn’t 在所有渠道中读起来相同。内部开发者、终端用户、支持人员和 beta 测试者不需要相同的详细信息。如果您推送一个通用的通知到所有渠道中，每个受众都会获得错误的信息。
对于多个受众的产品，一个实用的模式是层次化的格式：首先使用简洁的语言概述，然后添加面向用户的详细信息，最后添加可选的技术附录，用于实现说明、API 或迁移指南，以及故障排除。 ServiceNow 对发布说明最佳实践的讨论.
一个发布，多个读者
在实践中，这些受众有何不同。
| 受众 | 他们需要什么 | 避免什么 |
|---|---|---|
| 终端用户 | 明显的改进、可见的变化、行动项 | 工单ID、实现细节 |
| 技术人员 | 版本信息、迁移、API注意事项、已知问题 | 营销语言但不具体 |
| 内部团队 | 支持指南、发布时间、升级上下文 | 公开简化，隐藏运营风险 |
| 测试者 | 本次更新的变化、需要的反馈 | 公司范围内的全量更新日志噪音 |
一层笔记可以让您只需编写一次即可发布多次。摘要变成应用内卡片或推送消息。中间层变成公共更新日志条目。附录可以放入文档、GitHub发布或内部wiki中。
选择合适的频道
有些频道更适合速度。有些频道更适合细节。
- 应用内通知: 适合与用户遇到变化时的简要概述。
- 更新日志页面或博客文章: 更适合长期历史、搜索和链接。
- 电子邮件摘要: 适合管理员、倡导者和不每天登录的客户。
- 内部聊天或wiki: 最佳选择是支持脚本、发布状态和事件背景。
- 开发者文档或GitHub发布: 适合API、SDK或迁移细节。
错误在于将完整的说明复制到每个目的地。将顶层定制为频道，然后将读者链接到更深层次的层次，如果他们想要更多的信息。
如果您的团队已经在多个系统中管理文档和发布资产，标准化这些项目从草稿到发布状态的移动将有所帮助。MeshBase 的指南是该更广泛工作流程的实用参考，特别是如果发布说明与文档、更新和知识库内容并排放置。 用户打开您的应用程序想要信心和相关性。开发人员阅读发布历史想要精确性。支持负责人想要两者。最有效的发布说明程序将发布作为分发设计，而不是复制和粘贴。同一发布。不同的打包方式。
使用 CI/CD 和现代工具自动发布说明
手动发布说明在频繁发布时会出现问题。草稿落后于构建，某人忘记包含修复，发布的说明不再与实际发布内容匹配。
自动化解决了重复部分的问题。它并没有取代判断。
从 __CAPGO_KEEP_0__ 提交到最终发布的自动化发布说明工作流程的六步图表。
什么需要自动化，什么需要保留给人类
__CAPGO_KEEP_0__
__CAPGO_KEEP_0__
自动化:
- 变更提取 从提交、合并的拉取请求、标签和链接问题
- 草稿组装 将信息填入您的发布说明模板
- 版本和日期插入
- 发布步骤 到更改日志页面、GitHub发布或内容管理系统
- 通知 向内部团队发送批准后
保留人类审查:
- 优先级和排序
- 用户可见的措辞
- 敏感的变更
- 破坏性或回滚语言
- 关于性能、兼容性或所需操作的任何声明
这项分工可以节省时间而不发布机器人笔记。您的管道收集事实。 一个审阅者使它们有用。
可用的管道
一个实用的自动化流程在GitHub Actions、GitLab CI 或另一个 CI/CD 系统中通常如下所示:
- 一个发布标签或合并到发布分支触发作业。
- 一个脚本拉取合并的 PR 标题、提交消息和链接问题元数据。
- 管道根据标签如功能、修复和破坏性变更进行分组。
- 它生成一个 markdown 草稿，包含您标准格式的部分。
- 一个审阅者编辑摘要和任何高风险条目。
- 发布者发布发布说明并将其附加到发布artifact中。
您可以使用自定义脚本、平台中的发布工具或专门的助手来构建此项。 如果您想了解工具层的想法，值得浏览探索创新工具的社区，特别是那些试图减少手动清理后draft生成的团队。例如，Releasebot等创新工具
一支运行Capacitor应用的团队也可以将注释生成与部署管道和审批流程集成到一起。这 GitHub与Capgo的Actions集成指南 展示了如何将构建自动化与实时更新交付联系起来。
以下是实时更新自动化流程的视频教程:
实时更新改变了时间表
实时更新环境会引入新的复杂性。在传统的商店发布中，注释通常与通过应用审批推送的版本对齐。在实时更新工作流中，用户可能会在商店发布周期外接收JavaScript、CSS、复制、配置或资产更改。
这意味着您的发布说明过程需要回答两个独立的问题：
- 什么在二进制发布中被推送？
- 在实时捆绑包中发生了什么变化?
如果您支持即时传递，请在二进制说明和发布后更新说明之间保持可见的区别。否则，支持团队就无法知道哪些更改与商店版本相关，哪些更改在之后才到达。该空间中的一个选项是Capgo，它发布了签名的Web捆绑包，适用于Capacitor应用，并保留了与更新传递相关的版本历史、日志和回滚数据。
自动化在反映您的实际发布模型时最有效。如果您的团队持续发布，您的说明也应该持续生成，并在发布之前进行审查。
企业级回滚和合规说明
企业级发布说明更具权重，因为它们不仅仅是公开更新。它们可以成为审计文档、支持证据、事件参考和操作控制的证据。
这改变了您写它们的方式。简洁性仍然很重要，但可追溯性更重要。
为审计而非仅仅是公告而写
一个公共说明可能会说“改进了帐户恢复”。企业级发布记录也应该保留版本、发布日期、审批人、相关票据、风险分类、受影响系统和任何操作指示。
并非意味着将所有内容呈现在每个读者面前。它意味着以版本化的记录形式存储发布说明，具有多层详细信息。公共摘要在顶部。内部证据在下面。
对于受监管行业的团队，一个有用的基线是：
- 不可变的发布历史
- 命名的拥有者和审批人
- 链接的实施记录
- 发布的清晰状态（已发布、回滚或被取代）
- 热修复和紧急更改的分离处理
回滚说明需要自己的格式
回滚说明往往在紧急事件中被即兴编写。这很危险。回滚说明应该是一种首等的发布文档。
使用一个短结构：
| 字段 | 示例内容 |
|---|---|
| 回滚发布 | 版本或更新标识符 |
| 原因 | 用户可见问题、稳定性问题、兼容性问题 |
| 范围 | 受影响的用户 |
| 行动 | 团队做了什么 |
| 当前状态 | 已回滚、暂停、重新部署、监控 |
| 用户指南 | 用户或管理员应采取的行动 |
A回滚记录不应像缺乏信息一样读起来像道歉。它应该清晰地解释操作状态，并避免隐瞒事实，即更改已被撤销。如果您的应用程序支持实时更新，回滚控制需要紧密地与发布历史和部署通道相关联。在这种情况下，配置回滚的文档过程成为发布通信的一部分，而不是仅仅是应急响应。 configuring rollback for Capacitor updates 最差的回滚记录几乎什么都没有说。第二差的假装回滚没有发生。
衡量是否有行为发生变化
许多团队仍然没有解决的一个问题是，他们发布发布说明，但无法证明有人采取了行动。
产品分析供应商报告称，发布说明页面通常作为一个被动的公告渠道运行，而团队则努力将其与采用、支持转移或特征发现联系起来，正如本文所述的CalHEERS发布说明文档中所述。
这种差距在企业环境中更为重要，因为发布通信往往需要为其努力辩护。 一个实用的方法是在发布前定义一个小的信号集：特征发现：
用户是否在发布说明发布后打开或使用了更改的工作流程？
- 用户是否在发布说明发布后打开或使用了更改的工作流程？ 用户是否在发布说明发布后打开或使用了更改的工作流程？
- 影响支持: 受影响问题的提问是否减少了?
- 管理员行为: 目标账户是否完成了请求的操作?
- 事件清晰度: 在回滚或分阶段发布时，是否使用了注释作为参考点?
你不需要百分之百的归因。没问题。目标是停止将发布说明视为静态文档，开始将其视为运营杠杆。
如果您的团队频繁更新一个 Capacitor 应用程序, Capgo context
