Changeloop

changeloop 博客

发布说明实践

我们经常思考两件事：如何写出有人读的发布说明，以及如何不再手动维护 changelog。没有订阅，不用注册，只有文章。

  • 缺陷修复发布说明：怎样写出读者真正会用的条目

    缺陷修复发布说明想有用，每条都要写清症状、受影响的人群、起始时间和读者下一步该做什么。本文提供改写对照，并讲解安全修复、回归和数据丢失的写法。

    发布说明实践阅读约 1 分钟

  • 如何在软件产品中向客户征集反馈：时机、渠道与话术

    想在软件产品里收到有用的反馈，就要在用户刚完成某个操作后，在他们工作的地方，只问一个具体的问题。本文按时机和渠道给出现成话术，并说明拿到答案后如何回复。

    反馈闭环阅读约 1 分钟

  • 产品路线图示例：六种格式，以及各自是怎样失效的

    本文给出六个带真实条目的产品路线图示例：Now/Next/Later、季度时间线、主题式、结果式、公开路线图和发布路线图，说明各自适合的读者和失效之处。

    反馈闭环阅读约 1 分钟

  • 面向频繁发布团队的发布管理流程：七个步骤与关键指标

    本文介绍面向软件团队的七步发布管理流程，每步有明确负责人和退出标准，并介绍 DORA 指标和一项值得自己追踪的 KPI。

    工程实践阅读约 1 分钟

  • 发布说明示例：针对每一种变更类型的写法，以及为什么有效

    本文给出新功能、改进、缺陷修复、破坏性变更、安全修复、弃用、应用商店说明和内部说明的发布说明示例，并解释为什么有效，让你照搬形状，换上自己产品的真实事实。

    发布说明实践阅读约 1 分钟

  • Stripe API 版本控制的运作方式，以及值得借鉴的做法

    Stripe API 版本控制把每个账户固定在一个带日期的版本上，并允许单次请求覆盖它。本文讲这套机制如何运作、代价是什么，以及小型 API 可以借鉴哪些做法。

    API 变更阅读约 1 分钟

  • 体验日志到底是谁在写，又应该是谁来写才对

    谁来写体验日志？PR 作者清楚改了什么，产品经理清楚这对用户为什么重要，单靠任何一方都写不出客户真正能用的条目。

    工程实践阅读约 1 分钟

  • 紧急发布说明：如何在真实的时间压力下动笔写作

    严重事故触发的紧急发布，要在几分钟内写出可用且诚实的发布说明，而通常的写作流程默认写作者有从容的时间。本文说明在时间压力下，如何面对焦虑的读者动笔。

    发布说明实践阅读约 1 分钟

  • Protobuf 破坏性变更：线上格式到底能保住什么

    Protobuf 的破坏性变更发生在线上传输的字节流里，而不是 URL 路径。有些字段改动安全免费，有些会悄悄破坏所有老客户端，在代码 diff 里却几乎一样。

    API 变更阅读约 1 分钟

  • 体验日志文件格式：JSON、YAML，还是干脆用 Markdown

    体验日志的文件格式，决定它能否驱动页面和小组件，还是只能被人读一遍。本文讲 Markdown、JSON 和 YAML 各自的代价，以及何时值得迁移到结构化格式。

    工程实践阅读约 1 分钟

  • 重复的功能请求：怎么合并但不丢失原来的声音

    合并重复的功能请求能保住数字，但粗心合并会丢掉让某条请求真正有用的措辞。本文讲保留措辞的合并流程、如何识别误判、是否通知提出者，以及功劳记给谁。

    反馈闭环阅读约 1 分钟

  • GraphQL 模式变更：没有版本号的停用

    GraphQL 的 URL 里没有 v1 或 v2，字段通过指令在同一份共享模式上逐个停用。本文说明这会如何改变体验日志要给调用方交代的内容。

    API 变更阅读约 1 分钟

  • 该怎样写一份真正管用的 API 迁移指南

    API 迁移指南把一次不兼容的变更变成一份清单，而不是一次故障。本文说明它该写什么、何时发布、谁来写，以及为什么光靠一条体验日志记录不够。

    API 变更阅读约 1 分钟

  • 一个跑在 GitHub Actions 里的体验日志检查

    这个跑在 GitHub Actions 里的体验日志检查，会在缺少记录时拒绝合并，因为依赖人记得的步骤迟早会失效。本文讲它能验证什么、不能验证什么，以及紧急热修复怎么办。

    工程实践阅读约 1 分钟

  • 该怎样拒绝一个功能请求，又不失去这位客户

    闭环通常意味着告诉某人她要的东西已经发布，真正难的是说不，还要不伤害和客户的关系。本文说明什么让拒绝特别糟糕，好的拒绝怎样开口，并给出可直接使用的话术。

    反馈闭环阅读约 1 分钟

  • Feature flag 发布说明：该说什么，又该什么时候说

    Feature flag 发布说明必须分清代码合并和真正发布，因为有 flag 时两者不再同时发生。时机不对就关闭反馈闭环，是在通知别人一个看不见的功能。本文讲如何判断时机。

    反馈闭环阅读约 1 分钟

  • 功能请求应该怎样追踪，才不会把它们弄丢掉

    功能请求追踪通常只有两种失败方式：请求无处可去，或有了去处却没人回头看。本文说明能扛住这两种失败的机制、好用的分诊标签，以及如何决定优先级并做好闭环。

    反馈闭环阅读约 1 分钟

  • 支持工单对功能请求：你到底应该相信哪一个

    支持工单和功能请求看板衡量的是两种不同的信号，来自两类不同的用户。把一个渠道的激增与另一个渠道的激增直接等同，只会得出自信却完全错误的优先级排序。

    反馈闭环阅读约 1 分钟

  • 一条功能请求，实际上很可能是一份缺陷报告

    一张要求新增设置项的支持工单，很可能只是在绕开一个隐藏的缺陷。贴错标签会把它送到错的负责人和队列，浪费优先级信号，还拖慢真正的修复。本文讲如何分辨两者。

    反馈闭环阅读约 1 分钟

  • Git 标签、发布记录和你的体验日志该怎样对应

    Git 标签、一次发布和一条体验日志记录，是同一事件的三份记录，用途和读者各不相同。把它们混为一谈，正是体验日志偏离实际发布的原因，本文说明如何对应。

    工程实践阅读约 1 分钟

  • 对内 API 体验日志：对另一个团队来说，到底什么变了

    对外的 API 体验日志面对无法联系的读者，对内的读者可能就在两层楼之外，这改变了它的责任。本文讲这些差别、谁来维护调用方名单，以及和 monorepo 的关系。

    API 变更阅读约 1 分钟

  • 对内发布说明：除了客户，还有谁必须知道到底发生了什么

    支持和销售团队常从一头雾水的客户口中，才第一次得知有新功能上线。对内发布说明能解决这个问题，本文讲它该怎么写、谁来写、何时写，以及如何比客户更早送达。

    发布说明实践阅读约 1 分钟

  • 移动应用的发布说明：字数上限到底会砍掉什么

    App Store 和 Play Store 只给几行可见文字，一个链接都不给，网页版的写法在这样的预算下会失灵。本文用真实例子讲如何取舍，别把最重要的一句挤出预览区。

    发布说明实践阅读约 1 分钟

  • Monorepo 的体验日志：到底该合成一份，还是按包拆开

    Monorepo 可以为整个仓库维护一份体验日志，也可以每个包各一份，选错会让发布要么太吵，要么信息分散。本文讲如何判断，以及标签、版本号和提交说明怎样配合。

    工程实践阅读约 1 分钟

  • 该怎样发布一条新功能公告（而不是悄无声息）

    大多数新功能公告，最后都死在了一个没人会看第二遍的渠道里。本文说明该在哪里发布、第一句话说什么、怎样直接触达提出过请求的人，以及四种渠道如何搭配使用。

    发布说明实践阅读约 1 分钟

  • 功能请求越堆越多的时候，到底该怎样排优先级

    功能请求都已跟踪、分组、打好标签后，仍有个更难的问题：该先做哪一个。本文讲几种管用的优先级框架、RICE 是否适合功能请求，以及原始投票数掩盖了什么。

    反馈闭环阅读约 1 分钟

  • 企业发布说明：一个账户到底会变成什么样子

    企业发布说明必须针对运行私有构建版本的具体客户实例校准，不能照搬公开通用版本。校准出错，要么用客户还没有的改动让他们困惑，要么泄露内部路线图。

    发布说明实践阅读约 1 分钟

  • 语义化版本控制，应该怎样配合你的体验日志

    语义化版本控制让调用方在读任何内容之前，就知道这次发布可能带来多大影响。本文说明每个数字承诺了什么，以及一条记录应该交代什么。

    工程实践阅读约 1 分钟

  • API 的 Sunset 响应头：什么时候该发送它

    API 的 Sunset 响应头告诉客户端一个版本何时彻底停止应答，这和只说将来会停用的通知是两回事。本文讲 RFC 8594 的规定、这个响应头能否信任，以及提前限时停机。

    API 变更阅读约 1 分钟

  • 体验日志到底是什么，里面又该放些什么内容

    体验日志是对产品变化所做的带日期的记录，写给受这些变化影响的人看。本文说明它是什么、不是什么，以及好的体验日志放在哪里。

    发布说明实践阅读约 1 分钟

  • Webhook 体验日志：没人要求过的破坏性变更

    Webhook payload 的改动会悄无声息地出问题，因为没人能拒绝它，接收方可能带着错误值运行好几天。本文讲什么样的改动算破坏性变更，以及如何加版本并安全迁移。

    API 变更阅读约 1 分钟

  • API 体验日志: 该公开什么内容，又是谁在读它

    API 体验日志的读者，是要判断自己的代码下个月还能否正常运行的人。本文说明每条记录应该交代什么、放在哪里，以及调用方如何订阅。

    API 变更阅读约 1 分钟

  • 如何搭建一个人们真的会持续关注的体验日志页面

    体验日志页面只有让人一次次回来看，才值得认真搭建。本文说明它放在哪里、每条记录需要什么内容、信息流和标记语言怎么处理，以及小组件放在哪。

    工程实践阅读约 1 分钟

  • 真正会被完整读完的产品更新邮件模板到底长什么样

    会被读完的邮件，是发给提过请求的人的那一封。本文说明模板、四种更新邮件、标题写法、受众细分与用户同意。

    发布说明实践阅读约 1 分钟

  • 如何停用一个 API，又不至于失去它的开发者

    停用是一个带日期的承诺。本文说明停用时间线、通知模板、响应头，以及防止停用下线演变成一场事故的那一步关键操作。

    API 变更阅读约 1 分钟

  • 面向调用方设计的 API 版本控制最佳实践

    只对真正破坏兼容性的内容做版本管理，把版本号放在调用方看得见的地方，让旧版本运行到明确的截止日期。本文比较四种常见方案，并以对调用方的要求高低为标准。

    API 变更阅读约 1 分钟

  • 破坏性变更：哪些算、哪些不算，以及如何安全发布

    破坏性变更是指正确的调用方无法承受的变更。本文说明哪些算、哪些不算，如何在 CI 中提前发现，以及如何安全地发布出去。

    API 变更阅读约 2 分钟

  • 从体验日志的一侧去闭合客户反馈循环的方法

    当提出请求的人被告知功能已上线，反馈循环才算闭合。本文说明这个四步循环、它容易在哪里断裂，以及体验日志为什么能闭合它。

    反馈闭环阅读约 1 分钟

  • 最终能够真正变成体验日志条目的功能请求模板

    功能请求要有用，前提是功能上线时还能把它找出来。本文说明模板该长什么样、把请求分流到正确位置的标签有哪些，以及体验日志之后会读取哪些字段。

    反馈闭环阅读约 1 分钟

  • 用 issue 追踪系统打造三列式公开路线图

    公开路线图归根到底是一份关于未来的承诺，所以要保持精简，直接从已在追踪的 issue 生成，并靠 issue 上的一个标签让项目在各列之间移动。本文说明整套机制。

    反馈闭环阅读约 1 分钟

  • 体验日志的自动化，以及它自身所存在的局限

    收集、排版和发布可以交给自动化，唯独挑选和措辞必须由人来完成，没有例外。本文说明这条界线划在哪里，以及界线移动时会带来什么后果。

    工程实践阅读约 1 分钟

  • 从 conventional commits 到一份体验日志

    Conventional commits 能让体验日志内容被自动推导出来，但不会因此自动变得好读。本文说明这个约定带来什么好处、在哪里走到尽头，以及如何弥补两者之间的差距。

    工程实践阅读约 1 分钟

  • 体验日志与发布说明二者之间的区别到底是什么

    体验日志是供人查找的持续累积的记录，发布说明则是写给还在犹豫是否关心这次更新的人的一条精选消息。两者面向的读者不同，需要区别对待，本文说明如何划分。

    发布说明实践阅读约 1 分钟

  • 如何写出用户真正愿意花时间读完的发布说明

    只写错误修复和性能改进，算不上一条合格的发布说明。本文说明每条发布说明都必须回答的核心问题，并用一个真实案例对比修改前后的两个版本，展示该怎样写。

    发布说明实践阅读约 1 分钟

  • Keep a Changelog，真正落地实践之后的心得

    Keep a Changelog 这份规范只有短短一页，可真正落实时，大多数团队会渐渐偏离。本文说明它写了什么、刻意没回答什么，以及执行时常在哪里出错。

    工程实践阅读约 1 分钟

  • 值得团队真正长期坚持采用的发布说明最佳实践

    关于发布说明的大多数最佳实践清单，只是写作风格建议，并没触及问题的本质。本文谈的是能切实改变读者行为的做法，以及另外三个流传很广却几乎没有价值的常见误区。

    发布说明实践阅读约 1 分钟