据说程序员最讨厌的两件事是 “别人没有写文档” 和 “要我写文档”。
编写更新日志可是也落入此怪圈呢！
程序员不写文档
来自 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 列表读一遍？
更新日志应该包含哪些内容
站在库的使用者的角度来看，程序员们希望看到什么样的更新日志，不希望看到什么样的更新日志？
- 添加的接口
- 现有接口的改变
- 未来即将删除的接口
- 此版本已经删除的接口
- 此版本修复的 Bug
- 此版本的安全性改进
然而这些都写了会让编写者很痛苦的……
手工和自动化的结合
当存在 API 比较工具的时候，我们可以很容易地比较各个版本间 API 的变化，包括新增、改变、即将移除和已经移除。而这部分的内容由工具生成是没什么阅读障碍的。
另一部分，描述功能的手工编写会比较容易阅读。例如新增的功能、修改的功能、已经删除的功能。
优秀文档的参考
以下是 UWP 的开发文档，属手工和自动化结合生成。
本文会经常更新，请阅读原文： https://blog.walterlv.com/post/how-to-write-changelog-and-keep-it-updating.html ，以避免陈旧错误知识的误导，同时有更好的阅读体验。
本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。欢迎转载、使用、重新发布，但务必保留文章署名 吕毅 （包含链接： https://blog.walterlv.com ），不得用于商业目的，基于本文修改后的作品务必以相同的许可发布。如有任何疑问，请 与我联系 ([email protected]) 。