如何维护更新日志

更新日志是什么？

更新日志（Change Log）是一个由人工编辑，以时间为倒序的列表， 以记录一个项目中所有版本的显著变动。

为何要提供更新日志？

为了让用户和开发人员更简单明确的知晓项目在不同版本之间有哪些显著变动。

哪些人需要更新日志？

人人需要更新日志。无论是消费者还是开发者，软件的最终用户都关心软件所包含什么。 当软件有所变动时，大家希望知道改动是为何、以及如何进行的。

指导原则

• 记住日志是写给人的，而非机器。
• 每个版本都应该有独立的入口。
• 同类改动应该分组放置。
• 版本与章节应该相互对应。
• 新版本在前，旧版本在后。
• 应包括每个版本的发布日期。

变动类型

• Added 新添加的功能。
• Changed 对现有功能的变更。
• Deprecated 已经不建议使用，准备很快移除的功能。
• Removed 已经移除的功能。
• Fixed 对bug的修复
• Security 对安全的改进

如何减少维护更新日志的精力？

在文档最上方提供 Unreleased 区块以记录即将发布的更新内容。

这样有两大意义：

• 大家可以知道在未来版本中可能会有哪些变更
• 在发布新版本时，可以直接将Unreleased区块中的内容移动至新发 布版本的描述区块就可以了

当然有，下面就是一些糟糕的方式。

使用git日志

使用git日志作为更新日志是个非常不好的方式：git日志充满各种无意义的信息， 如合并提交、语焉不详的提交标题、文档更新等。

提交的目的是记录源码的演化。 一些项目会清理提交记录，一些则不会。

更新日志的目的则是记录重要的变更以供最终受众阅读，而记录范围通常涵盖多次提交。

但这是个重要的参考，特别是规范的 git 日志。

无视即将弃用功能

当从一个版本升级至另一个时，人们应清楚（尽管痛苦）的知道哪些部分将出现问题。 应该允许先升级至一个列出哪些功能将会被弃用的版本，待去掉那些不再支持的部分后， 再升级至把那些弃用功能真正移除的版本。

即使其他什么都不做，也要在更新日志中列出derecations，removals以及其他重大变动。