如何写好 Changelog

在工作中需要写很多项目文档，随着不断的迭代，内容也会不断的变化，时间一长，就很可能忘记之前在什么时候做过什么改动了，所以这个时候就需要文档的写作者保持更新 Changelog 来确保每一个协作者都在同一个步伐。

• 很多人认为更新日志好像是只有「写代码」才需要的一个文档，但是只要涉及到文档协同、对1个文档进行长期的迭代，我们都需要一个更新文档来记录历史变动，这样新的人进来就可以对整个来龙去脉有一个非常直观的了解。

什么是更新日志

那什么是更新日志呢？更新日志（Change Log）是一个由人工编辑，以时间为倒叙的列表。 这个列表记录所有版本的重大变动。

一个非常直观的案例 我们可以看下 社区比较优秀的框架 [ant-design](https://github.com/ant-design/ant-design) 他们是如何写的 Antd-Changelog链接

可以看到在大型开源项目中 一个简洁明了、层次清晰的 Changelog 是非常重要的，还有一些 Emoji ～ 更加生动 哈哈～

总结一下：

一份优秀的Changelog，应具备：

• 给人而不是机器写的。记住，要说人话。

• 快速跳转到任意段。所以采用markdown格式

• 一个版本对应一个章节。/

• 最新的版本在上，最老的在下面。

• 所有日期采用’YYYY-MM-DD’这种规范。（例如北京奥运会的2008年8月8日是2008-08-08）这个是国际通用，任何语言 都能理解的，并且还被xkcd推荐呢！

• 标出来是否遵守语义化版本格式

• 每一个软件的版本必须：

• 标明日期（要用上面说过的规范）

• 标明分类（采用英文）。规范如下git：

• ‘Added’ 添加的新功能

• ‘Changed’ 功能变更

• ‘Deprecated’ 不建议使用，未来会删掉

• ‘Removed’ 之前不建议使用的功能，这次真的删掉了

• ‘Fixed’ 改的bug

• ‘Security’ 改的有关安全相关bug

• 另外关于命名规范，他也建议直接将更新日志命名为：CHANGELOG.md，注意大小写。

ISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md

• 这么多文件name 太不统一了 ⬆️
• 也有专门那么一群人定义了一份Changelog标准 参考 keepachangelog.com是一个致力于规范更新日志的项目.

完

本文部分参考网络侵删 Author：ruoduan  同步Blog