CHANGELOG.md(更新日志)格式规范

小学老师说：好脑子不如烂笔头

前言

作为一个普通的开发者，我必须为我的项目维护一个更新日志（以下简称 changelog）吗？

• 如果你在维护一个开源项目，或者公司内部的底层技术产品，那么提供一个 changelog 是必需的。开发者用户很可能需要从一个低版本升级到最新版，changelog 可以帮助他们了解新版本有哪些变化。
• 如果你在开发一个业务应用，那么 changelog 不是必需的。然而提供一个 changelog 会更好，因为其他协作者或是交接方能更直观地看到业务逻辑的演变。

我记得你还约束了 Git log 的规范，那为何还要再规范 changelog 的格式呢？两者不是差不多？

• 即便是约束了 Git log 的规范，也无法直接将 Git log 导出一个良好的 changelog。因为 changelog 中描述的内容需要更加精炼和归纳，对信息降噪处理等等，因此手写 changelog 仍然是更好的选择；当然，不排除以后自动转换的可能。
• 不管是手写还是自动转换，changelog 的格式都不能直接照搬 Git log 的格式。这两者的区别与联系同在。

changelog 文件

changelog 文件必须取名为 CHANGELOG.md，存放在项目的根目录下，和 README.md、CONTRIBUTING.md 等并列，同时保持风格一致。

这种命名方式已然是国际通则，以下再阐释一番：

使用大写来表明本文件的重要性，相当于是项目仓库元信息的一部分。 使用 .md 作为后缀，而不是 .txt 或干脆不加后缀。使用标准 Markdown 语法，从而可以方便地渲染。

基本的 changelog 格式

# 更新日志

## [<version>] - <date>

### <type>

* <desc>
* <desc>

### <type>

* <desc>
* <desc>

[<version>]: <version-diff-url>

其中，按照最新的版本号在前的顺序排列。

词汇表

标题

标题部分使用固定的文案：「更新日志」。

如果是面向国际的项目，需要使用英文，则文案为「Change Log」。

version

版本号 version 即项目的每一个发布版所使用的版本号。版本号需遵循 SemVer 版本号命名规范。

注意：版本号前不要加 v。

另外，版本号建议增加一个链接，指向当前版本和上一个版本之间的 diff。详情可参考后文的样本示例。

date

发布时间 date 即版本发布时的所在日期。

日期采用 yyyy-MM-dd 的格式。

示例：

// good
2016-01-01

// bad
2016-1-1
20160101

type

更新类型 type 用以说明更新的方面。这里的 type 和 Git 提交日志中的 type 有所联系，然而并不一一对应。

同前面提到的「标题」部分，默认使用中文版本的词汇，如果是面向国际的项目，则使用括号中的英文版本。

type 的可选值如下：

• 新增（Features）：新增功能。
• 修复（Fixed）：修复 bug。
• 变更（Changed）：对于某些已存在功能所发生的逻辑变化。
• 优化（Refactored）：性能或结构上的优化，并未带来功能的逻辑变化。
• 即将删除（Deprecated）：不建议使用 / 在以后的版本中即将删除的功能。
• 删除（Removed）：已删除的功能。

  desc

描述内容 desc 需要注意：

1. 使用完整的句子。即在标点方面遵循一般的文档格式规范；如果使用英语，则句首大写。
2. 时态方面使用一般现在时，不要用过去时态。虽然查看 changelog 时，changelog 内容本身都发生在过去，然而使用现在时的时态更简洁明确，并且更易达成一致性。
3. 句式使用祈使句式。即一般情况不要增加主语。因为在绝大情况下，主语都是作者「我」。
4. 注明修复的问题。如有提过 issue，则在句尾增加 issue 的 ID 和链接。

样本示例

# 更新日志

## [6.2.4] - 2015-12-16

### 变更

* `Node.fn.map()` 之前返回 NodeList 自身，现在将正确地返回被 map 后的数组。

### 修复

* 修复在非 ks-debug 模式下仍然输出 `KISSY.log()` 控制台信息的问题。

## [6.2.3] - 2015-11-16

### 修复

* 修复 `KISSY.getScript` 在传入了 `timeout` 参数后报错的问题。[#12]

## [6.2.2] - 2015-11-04

### 新增

* node 模块增加 API `Node.fn`，以兼容传统 KIMI 的 node 对象扩展机制。 
* ua 模块现在可以识别 Microsoft Edge 浏览器。

### 优化

* `KISSY.getScript()` 从 loader 模块中独立出来，io 模块不再依赖 loader 模块。

### 已删除

* io 模块默认去掉了对 XML 的 converter 支持。

参考资料

1. Keep a CHANGELOG
2. The Discussion about Change Log
3. 更新日志格式规范