发布了一款库（或工具包），如何持续地编写更新日志（ChangeLog）？

据说 程序员 最讨厌的两件事是 “别人没有写文档” 和 “要我写文档”。

编写更新日志可是也落入此怪圈呢！

程序员不写文档

来自 GitHub 的开源调查问卷结果直接显示，最令人头痛的莫过于文档了：

Incomplete or outdated documentation is a pervasive problem, observed by 93% of respondents, yet 60% of contributors say they rarely or never contribute to documentation. When you run into documentation issues, help a maintainer out and open a pull request that improves them.

▲ 来自 http://opensourcesurvey.org

自动化

我曾经试图找到一些自动化的方式来生成更新日志，例如：

• 查找 git 提交日志
• 查找 issues 问题

然而，这样生成的日志真难看懂！不信你试着把一个项目的 Issues 列表读一遍？

更新日志应该包含哪些内容

站在库的使用者的角度来看，程序员们希望看到什么样的更新日志，不希望看到什么样的更新日志？

1. 添加的接口
2. 现有接口的改变
3. 未来即将删除的接口
4. 此版本已经删除的接口
5. 此版本修复的 Bug
6. 此版本的安全性改进

然而这些都写了会让编写者很痛苦的……

手工和自动化的结合

当存在 API 比较 工具 的时候，我们可以很容易地比较各个版本间 API 的变化，包括新增、改变、即将移除和已经移除。而这部分的内容由工具生成是没什么阅读障碍的。

另一部分，描述功能的手工编写会比较容易阅读。例如新增的功能、修改的功能、已经删除的功能。

优秀文档的参考

以下是 UWP 的开发文档，属手工和自动化结合生成。

本文会经常更新，请阅读原文： https://walterlv.github.io/post/how-to-write-changelog-and-keep-it-updating.html ，以避免陈旧错误知识的误导，同时有更好的阅读体验。

本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。欢迎转载、使用、重新发布，但务必保留文章署名 吕毅 （包含链接： https://walterlv.github.io ），不得用于商业目的，基于本文修改后的作品务必以相同的许可发布。如有任何疑问，请 与我联系 。