体验日志的自动化，以及它自身所存在的局限
阅读约 1 分钟 更新于
体验日志的自动化，在它自动化收集、分类和发布这三步、并在挑选和措辞这两步停下时才真正有效。把整个流程都自动化，你发布的就是一份排过版的 git log；一步都不自动化，体验日志就会在发布前从记忆里临时赶出来。真正有用的问题是应该自动化哪些部分，而不是应该自动化多少。
体验日志自动化项目会在两个方向之一失败，而且从第一次设计会议起就能预见到。自动化得太少，体验日志就会变成一份”应该有人去更新”的文档，意味着它会被抽到短签的那个人断断续续地更新。自动化得太多，它就会变成一份排过版的 git log：完整、准确，却没人读。
体验日志的哪些部分应该自动化
四个步骤里的三个。收集和发布完全自动化；分类作为第一遍处理，交由人工复核；挑选和措辞永远不自动化。
| 步骤 | 是否自动化？ | 原因 |
|---|---|---|
| 收集：从提交、PR、工单中把变化整理成一份清单 | 完全自动化 | 枯燥，赶工期时容易被跳过，机器能做到完美 |
| 分类：Added、Fixed、Changed、Deprecated、Removed、Security | 先自动跑一遍，再由人工复核 | 仅凭元数据大约能做对 80%，出错的那 20% 恰恰是最重要的条目 |
| 挑选和措辞：告诉读者什么、怎么说 | 永远不自动化 | 这是这份成果物全部的价值所在 |
| 发布：页面、信息流、邮件、小组件、Slack | 完全自动化，且来自同一个来源 | 大多数手工劳动实际发生的地方 |
收集。 把变化从它们发生的地方（提交、PR、工单）取出来，整理成一份清单。把这一步完全自动化。人类不擅长做这件事，它很枯燥，而且是赶工期时最容易被跳过的一步。Conventional commits或 PR 标签通常就是这一步的原材料。
分类。 判断某个变化到底是 Added、Fixed、Changed、Deprecated、Removed 还是 Security。从提交类型或 PR 标签自动跑出第一遍结果，再让人工去复核修正。仅凭元数据，这里的准确率大约在百分之八十左右，而出错的那百分之二十，恰恰集中在最重要的那些条目上，因为模糊性和重要性是相关的。
挑选和措辞。 决定应该告诉读者什么，以及怎么说。不要把这一步自动化。 这是这份成果物全部的价值所在，其余的一切都只是物流工作。
发布。 把写好的条目送到页面、信息流、邮件、应用内小组件、Slack 频道。完全自动化，并且来自同一个来源。这正是大多数手工劳动实际发生的地方，却几乎没人去统计它。这也是能够告诉当初提出这个变化的人”它已经上线了”的那一步，这正是从体验日志一侧闭合反馈循环的全部内容。这一步里邮件所承担的那一半，在产品更新邮件模板里有它自己的形式。
最后这一点值得多想一想。团队往往把体验日志当成一个写作问题，然后把大部分时间花在分发上：把条目复制进邮件工具，为应用内展示重新排版，粘贴进 Slack，更新一个文档页面。写作只需要一个小时。而复制粘贴每次发布都要花一个小时，永远如此，而这正是应该交给机器去做的部分。
这条界线移动时会发生什么
向上移，你会得到一份 git 大杂烩。 完全从提交自动化生成，会把 bump deps、fix flaky test、wip、address review comments 直接摆到客户面前。所有这样做过的团队，最后都加上了一个过滤器，而这个过滤器其实就是挑选这一步换了个名字重新出现，体验反而更差了。
向下移，你会得到一堆临时赶工的内容。 完全靠人工收集，意味着条目是在发布时凭记忆写出来的。这正是 Keep a Changelog 一开篇就在警告的那种模式，它会悄悄地劣化：体验日志看起来一直维护得很好，直到某一周所有人都没时间为止。
一条体验日志自动化流水线是什么样的
四个步骤，恰好一个人工关卡，放在草稿变成公开内容的那个节点上。
- 在合并时，从 PR 推导出一条草稿条目：类型来自标签或提交前缀，标题作为初稿，链接回 PR，记录作者。把它放进一个未发布的池子里。
- 任何人在任何时候都可以编辑任何草稿，编辑的成本很低。大多数只需要改写一行。
- 要切出一次发布，池子里的每一条条目都必须已经被编辑过，或者被明确标记为内部条目。这个关卡就是整个设计的核心。没有它，草稿就会在忙碌的那一周未经编辑地直接发布出去。
- 发布是从已发布的集合扇出出去：公开页面、信息流、邮件、小组件、Slack 帖子。一个来源，多种渲染，不需要复制。
第三步是唯一需要人的地方，一旦草稿质量不错，每次发布大约只需要十分钟。当涉及客户的请求时，草稿也会带着它所关闭的那个 issue，这正是第四步能够告知请求者的原因；功能请求模板的设计正是为了让这条链接能够存活下来。这一步在更大的发布流程中处于什么位置，是发布管理流程一文的主题。
自动化对你的数据有什么要求
如果体验日志是一份 Markdown 文件，上面这一切都行不通，因为一份文件如果不重新解析回来，就无法渲染到五个不同的展示面，而解析散文的结果，就是你最终会得到一个只显示了半个标题的小组件。
条目需要是结构化的：类型、日期、版本或发布标识、目标读者、正文和链接。有了这些，文件、页面、信息流和邮件就都成了同一份数据的不同视图。这个结构性的点，是在选择工具之前唯一值得先做对的事情，因为它是之后无法低成本补救的东西。如果每一个需要一条记录的改动都没有真正生成那条记录，上面这一切都不管用；在 CI 里强制要求一条体验日志记录讲的是怎么让流水线拒绝没有记录的合并，而不是把这一步交给人的记性。
我们在构建 changeloop，在这里体验日志首先是一个信息流，其次才是一个页面，所以请把这段话当作利益相关的立场，而不是中立的推荐来看；定价提供一个无需信用卡的免费仓库，足够看清它的形态。体验日志工具是我们对现有其他选择的汇总，包括我们的竞争对手，体验日志生成器则可以在浏览器里完成收集和分类这两步，如果你想在投入一整条流水线之前先看看推导的效果。
这个测试
数一数从一个变化被合并，到那个不读你仓库的客户能看见它，中间隔了多少分钟。如果大部分时间都花在有人在不同工具之间复制文字，那么你需要的自动化在发布环节，而不是写作环节。
FAQ
AI 能写体验日志吗? 它能起草一份。给一个模型一个已经合并的 pull request，大多数情况下它能产出一份可用的标题和正文初稿，这相当于把收集和分类这两步做得更好了。而挑选——即是否应该告诉读者，以及最终的措辞——依然需要一个了解目标读者的人来完成，一条不带这个关卡就发布草稿的流水线，自动化的是错误的那一步。
体验日志生成器和体验日志自动化有什么区别? 生成器是在需要的时候，把提交一次性转换成一份排好版的列表。自动化则是在每次合并时运行，维护一个未发布的池子，把发布的条件设为人工审核，并从同一个来源发布到每一个展示面。生成器是这条流水线的第一步，由人手动运行。
体验日志应该从提交自动化，还是从 pull request 自动化? 应该从 pull request，因为在这里变化的单位就是 PR：标题和描述是针对整个变化写一次的，而 PR 会链接它所关闭的 issue。基于提交的推导，在提交就是变化单位、并且遵循某种约定书写时才有效。
怎样阻止自动化发布内部变更?
把 chore、ci、test、refactor 和依赖升级默认分类为内部条目，把提升为公开条目变成一个刻意的动作。反过来的默认设置——默认公开，除非有人把它隐藏起来——正是 bump deps 会传到客户那里的原因。
本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。