更新日志格式规范

一个项目 / 产品需要向人们介绍自己经历的历史，这对用户以及开发者而言，都有益处。

关于本规范的任何建议和意见，请移步 [issue][] 页面反馈给我们，谢谢！

前言

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

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

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

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

changelog 文件

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

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

1. 使用大写来表明本文件的重要性，相当于是项目仓库元信息的一部分。
2. 使用 .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 支持。

渲染效果见 [KISSY 的更新日志][kissy-changelog]。

参考资料

1. Keep a CHANGELOG
2. The Discussion about Change Log