更新日志格式規(guī)范
一個(gè)項(xiàng)目 / 產(chǎn)品需要向人們介紹自己經(jīng)歷的歷史，這對(duì)用戶以及開發(fā)者而言，都有益處。
關(guān)于本規(guī)范的任何建議和意見，請(qǐng)移步 [issue][] 頁面反饋給我們，謝謝！
前言
作為一個(gè)普通的開發(fā)者，我必須為我的項(xiàng)目維護(hù)一個(gè)更新日志（以下簡(jiǎn)稱 changelog）嗎？
- 如果你在維護(hù)一個(gè)開源項(xiàng)目，或者公司內(nèi)部的底層技術(shù)產(chǎn)品，那么提供一個(gè) changelog 是必需的。開發(fā)者用戶很可能需要從一個(gè)低版本升級(jí)到最新版，changelog 可以幫助他們了解新版本有哪些變化。
- 如果你在開發(fā)一個(gè)業(yè)務(wù)應(yīng)用，那么 changelog 不是必需的。然而提供一個(gè) changelog 會(huì)更好，因?yàn)槠渌麉f(xié)作者或是交接方能更直觀地看到業(yè)務(wù)邏輯的演變。
我記得你還約束了 Git log 的規(guī)范，那為何還要再規(guī)范 changelog 的格式呢？?jī)烧卟皇遣畈欢啵?/p>
- 即便是約束了 Git log 的規(guī)范，也無法直接將 Git log 導(dǎo)出一個(gè)良好的 changelog。因?yàn)?changelog 中描述的內(nèi)容需要更加精煉和歸納，對(duì)信息降噪處理等等，因此手寫 changelog 仍然是更好的選擇；當(dāng)然，不排除以后自動(dòng)轉(zhuǎn)換的可能。
- 不管是手寫還是自動(dòng)轉(zhuǎn)換，changelog 的格式都不能直接照搬 Git log 的格式。這兩者的區(qū)別與聯(lián)系同在。
changelog 文件
changelog 文件必須取名為 CHANGELOG.md，存放在項(xiàng)目的根目錄下，和 README.md、CONTRIBUTING.md 等并列，同時(shí)保持風(fēng)格一致。
這種命名方式已然是國(guó)際通則，以下再闡釋一番：
- 使用大寫來表明本文件的重要性，相當(dāng)于是項(xiàng)目倉庫元信息的一部分。
- 使用
.md作為后綴，而不是.txt或干脆不加后綴。使用標(biāo)準(zhǔn) Markdown 語法，從而可以方便地渲染。
基本的 changelog 格式
# 更新日志
## [<version>] - <date>
### <type>
* <desc>
* <desc>
### <type>
* <desc>
* <desc>
[<version>]: <version-diff-url>
其中，按照最新的版本號(hào)在前的順序排列。
詞匯表
標(biāo)題
標(biāo)題部分使用固定的文案：「更新日志」。
如果是面向國(guó)際的項(xiàng)目，需要使用英文，則文案為「Change Log」。
version
版本號(hào) version 即項(xiàng)目的每一個(gè)發(fā)布版所使用的版本號(hào)。版本號(hào)需遵循 SemVer 版本號(hào)命名規(guī)范。
注意：版本號(hào)前不要加 v。
另外，版本號(hào)建議增加一個(gè)鏈接，指向當(dāng)前版本和上一個(gè)版本之間的 diff。詳情可參考后文的樣本示例。
date
發(fā)布時(shí)間 date 即版本發(fā)布時(shí)的所在日期。
日期采用 yyyy-MM-dd 的格式。
示例：
// good
2016-01-01
// bad
2016-1-1
20160101
type
更新類型 type 用以說明更新的方面。這里的 type 和 Git 提交日志中的 type 有所聯(lián)系，然而并不一一對(duì)應(yīng)。
同前面提到的「標(biāo)題」部分，默認(rèn)使用中文版本的詞匯，如果是面向國(guó)際的項(xiàng)目，則使用括號(hào)中的英文版本。
type 的可選值如下：
- 新增（Features）：新增功能。
- 修復(fù)（Fixed）：修復(fù) bug。
- 變更（Changed）：對(duì)于某些已存在功能所發(fā)生的邏輯變化。
- 優(yōu)化（Refactored）：性能或結(jié)構(gòu)上的優(yōu)化，并未帶來功能的邏輯變化。
- 即將刪除（Deprecated）：不建議使用 / 在以后的版本中即將刪除的功能。
- 刪除（Removed）：已刪除的功能。
desc
描述內(nèi)容 desc 需要注意：
- 使用完整的句子。即在標(biāo)點(diǎn)方面遵循一般的文檔格式規(guī)范；如果使用英語，則句首大寫。
- 時(shí)態(tài)方面使用一般現(xiàn)在時(shí)，不要用過去時(shí)態(tài)。雖然查看 changelog 時(shí)，changelog 內(nèi)容本身都發(fā)生在過去，然而使用現(xiàn)在時(shí)的時(shí)態(tài)更簡(jiǎn)潔明確，并且更易達(dá)成一致性。
- 句式使用祈使句式。即一般情況不要增加主語。因?yàn)樵诮^大情況下，主語都是作者「我」。
- 注明修復(fù)的問題。如有提過 issue，則在句尾增加 issue 的 ID 和鏈接。
樣本示例
# 更新日志
## [6.2.4] - 2015-12-16
### 變更
* `Node.fn.map()` 之前返回 NodeList 自身，現(xiàn)在將正確地返回被 map 后的數(shù)組。
### 修復(fù)
* 修復(fù)在非 ks-debug 模式下仍然輸出 `KISSY.log()` 控制臺(tái)信息的問題。
## [6.2.3] - 2015-11-16
### 修復(fù)
* 修復(fù) `KISSY.getScript` 在傳入了 `timeout` 參數(shù)后報(bào)錯(cuò)的問題。[#12]
## [6.2.2] - 2015-11-04
### 新增
* node 模塊增加 API `Node.fn`，以兼容傳統(tǒng) KIMI 的 node 對(duì)象擴(kuò)展機(jī)制。
* ua 模塊現(xiàn)在可以識(shí)別 Microsoft Edge 瀏覽器。
### 優(yōu)化
* `KISSY.getScript()` 從 loader 模塊中獨(dú)立出來，io 模塊不再依賴 loader 模塊。
### 已刪除
* io 模塊默認(rèn)去掉了對(duì) XML 的 converter 支持。
渲染效果見 [KISSY 的更新日志][kissy-changelog]。
