如何撰写客户愿意读的更新日志(和发布说明)

作者: Fraser Hardy

已合并的拉取请求经过筛选,汇入带日期的更新日志,其中包含“新增”“改进”和“修复”条目

上个月您上线了十几项内容,而您的更新日志上写的是“错误修复和性能改进”。

一直在等某个修复的客户,完全不知道它已经上线。拿您和竞品做比较的潜在客户,看到的是一个似乎从春天起就没有任何动静的产品。

下面讲讲怎样写出人们真正会读的更新日志。为客户写,而不是为合并代码的人写。每一条都标注日期。把变更归入新增、改进和修复三类。每一条都以“现在可以做什么”开头,用一句话说明它为什么重要,并告诉读者去哪里找。凡是客户看不到的,以及尚未上线的内容,一概不写。然后按稳定的节奏发布,哪怕有些周的内容很短。

这就是大部分要点。本文其余的部分是一份模板、一组差与好的示例,以及一套把已合并的 PR 变成已发布说明、又不会占掉您整个周五的流程。

更新日志与发布说明:有什么区别?

人们常把这两个词混着用,但其实对应着两类读者。

开发者更新日志通常是代码仓库里的 CHANGELOG.md。它面向的是与您的 API、SDK 或库集成的人。他们关心的是版本号、破坏性变更和弃用。Keep a Changelog 是这方面的标准参考,它的约定很合理:最新的在前,每个版本一个小节,变更分为“新增”“变更”“弃用”“移除”“修复”和“安全”,并在顶部设一个“未发布”小节,用来放已合并但尚未发布的工作。

发布说明(也叫“产品更新”,或公开的更新日志页面)面向的是使用产品的客户。他们不在乎您升级了一个依赖项,他们想知道的是:现在能做到哪些上周还做不到的事。

如果您经营的是 SaaS 产品,您大概更需要第二种,而不是第一种。许多团队两种都需要,这没问题:同一份已合并工作的清单,可以支撑两份文稿。只是不要把开发者版本发布出去,然后称之为发布说明。

一份可以直接套用的发布说明模板

它适用于每周或每两周一次的产品更新,无论是放在更新日志页面、应用内的小组件,还是作为电子邮件。

## 6 October 2026

### New
**[What you can now do, in plain words]**
[One or two sentences: what it does and who it's for.]
Find it in **[Page > Section]**. [Link to help article]

### Improved
**[The thing that got better]**
[What's different from before, in terms the customer notices:
faster, fewer clicks, works on mobile, handles bigger files.]

### Fixed
- [Symptom the customer saw], now fixed.
- [Symptom the customer saw], now fixed.

### Heads up (only if needed)
**[Anything changing or going away]**
[What's happening, when, and what they need to do.]

让它奏效的几条规则:

差与好的更新日志条目

一条写成提交信息的糟糕更新日志条目,旁边是一条解释对客户有何变化以及去哪里找的优秀条目

最常见的失败,是直接粘贴提交信息。它看起来是这样的:

v2.14.0
- feat(export): csv async job
- fix: tz bug in reports
- refactor billing svc
- bump deps
- misc improvements

里面的每一句都是真的,但没有一句对客户有用。有两条是内部噪音,一条毫无意义(“misc improvements”),而那两项真正的变更,写的是给审阅 PR 的人看的。

下面是同一次发布,改写之后:

6 October

NEW: Big CSV exports run in the background
Exports over 10,000 rows no longer time out. Start the export
and we'll email you a link when the file is ready.
Find it in Reports > Export.

FIXED: Report dates now match your timezone
Daily totals were splitting at midnight UTC instead of your
local midnight, so some days looked short. They're correct now,
including for past reports.

五条变成了两条。每一条都说明了什么变了、读者为什么要在意,以及去哪里看。重构和依赖升级被删掉了,因为没有客户会注意到它们。

再看几组对照,因为这种写法要养成习惯需要一段时间:

差好
新增 SSO使用 Okta 或 Google Workspace 登录。 管理员可以在“设置 > 安全”中开启。
提升了性能大型账户的仪表盘加载快得多。 包含数千个条目的项目在首次加载时不再卡顿。
修复了通知的 bug当有人在同一条评论中两次提到您时,您不会再收到重复的邮件。
弃用 v1 接口v1 API 将于 3 月 1 日停止工作。 请在此之前迁移到 v2。以下是具体变化。

请注意,“快得多”是含糊的。如果您有测量得到的真实数字,就用它;如果没有,就描述使用体验,而不是编造一个百分比。

如何根据已合并的 PR 撰写更新日志

更新日志的五步流程:收集已合并的 PR,筛选出客户可见且已上线的变更,按类型分组,为客户改写,附上链接后发布

大多数团队的难处不在于写作,而在于记住发布了什么。下面是一套经得起考验的流程。

1. 收集。 列出自上一条更新日志以来合并的所有内容。借助 GitHub CLI:

gh pr list --state merged \
  --search "merged:>=2026-10-27" \
  --json number,title,labels,mergedAt,url \
  --limit 100

2. 筛选。 对每个 PR 问两个问题:客户能看到或感受到这个变化吗?它对客户来说真的已经上线了吗?内部重构、CI 变更和测试修复都剔除。任何位于尚未开启的功能开关之后的内容,也一并剔除。宣布客户还用不了的工作,比不宣布更糟糕,因为您会收到“它在哪里?”的工单。

3. 分组。 把剩下的内容分入新增、改进和修复。几个小的 PR 往往合起来只是一条(“批量编辑”可能是四个 PR)。

4. 改写。 用模板把每一组变成一条记录。先说好处,用平实的话,说明去哪里找。

5. 发布并链接。 发布出去,把每个新功能链接到它的帮助文章,并分享到您的客户能看到的任何地方。

让第 4 步轻松得多的窍门,是在提交 PR 时就索要面向客户的那句话,趁作者还记得自己做了什么。在 .github/pull_request_template.md 中添加一个小节:

## Customer-facing change
<!-- One sentence a customer would understand, or "None". -->
<!-- e.g. "You can now export reports over 10,000 rows." -->

- [ ] Behind a feature flag (don't announce until it's on)
- [ ] Help articles checked

最后那个复选框很重要。每一项涉及界面的上线变更,都可能让某篇帮助文章过时,而更新日志正是发现这一点的好时机。我们在如何让文档保持最新中讲了这一方面。

产品更新应该多久发布一次?

在合理范围内,与您的发布节奏保持一致。如果您持续发布,那么每周或每两周一次的汇总,读起来比每次部署写一条要好;如果您每月发布一次,就每月发布一次。

比频率更重要的是持续性。一份更新日志在一月有三条记录,此后就再没有动静,它传达的信息可能并不是您想表达的。内容少的一周没关系。“这周有两个修复,下周会有更大的发布”,比沉默要好。

重大发布值得更多的投入,而不只是更新日志里的一行:一篇正式的公告、一封邮件,也许还有一段短视频。更新日志是持续的记录,而不是完整的营销计划。

更新日志放在哪里

Beamer、Headway、LaunchNotes 或 Canny 的更新日志功能这类专用工具,能很好地处理小组件和邮件方面的需求。许多团队直接用文档站点上的一个页面。工具的重要性不如习惯。

Ellie Docs 的定位

声明一下:这是我们专门为之打造产品的问题。Ellie Docs 会关注您已合并的 PR,并据此起草更新日志条目,写给客户看,而不是写给审阅者看。对于尚未发布或位于功能开关之后的工作,它会暂缓收录,这样您就不会宣布人们用不了的东西。每一条记录,由您编辑、丢弃或发布。没有任何内容会自行发出。

Ellie Docs 的更新日志视图,显示根据已合并的拉取请求起草的、对客户友好的条目,每一条都链接到相关的帮助文章,可供编辑或发布

因为它同时也在维护您的帮助中心,所以产生一条更新日志条目的那个 PR,也会为任何现已过时的文章生成一条建议的更新,以差异对比的形式呈现,由您接受或忽略。

某个拉取请求之后对帮助文章的建议更新,以红绿差异对比的形式显示,带有“接受”和“忽略”按钮

如果您的更新日志目前只是一串提交标题,或者自上线以来就没动过,这就是它所填补的空缺。如果您乐于手写,上面的模板和 PR 检查清单能帮您完成大部分工作。

几个常见问题

更新日志应该包含错误修复吗? 应该,那些客户注意到的。修复某个有人反馈过的 bug,是您能发布的、最受关注的内容之一,尤其是当您告知了反馈的那个人。团队以外的人从未见过的修复,则可以略过。

我需要版本号吗? 对于 API、SDK 或任何需要安装的东西,需要,并且遵循语义化版本,让人们一眼就能判断风险。对于持续部署的 Web 应用,日期更清晰。客户并不以版本来思考。

一条更新日志应该写多长? 一个加粗的标题,加上一到三句话。如果需要更多,就写一篇帮助文章或博客文章,并链接过去。

想让您的更新日志根据已经合并的 PR 来起草吗?免费试用 Ellie Docs。有免费方案,无需绑定银行卡。