小學老師說：好腦子不如爛筆頭

前言

作為一個普通的開發(fā)者，我必須為我的項目維護一個更新日志（以下簡稱 changelog）嗎？

如果你在維護一個開源項目，或者公司內部的底層技術產品，那么提供一個 changelog 是必需的。開發(fā)者用戶很可能需要從一個低版本升級到最新版，changelog 可以幫助他們了解新版本有哪些變化。 如果你在開發(fā)一個業(yè)務應用，那么 changelog 不是必需的。然而提供一個 changelog 會更好，因為其他協(xié)作者或是交接方能更直觀地看到業(yè)務邏輯的演變。

我記得你還約束了 Git log 的規(guī)范，那為何還要再規(guī)范 changelog 的格式呢？兩者不是差不多？

即便是約束了 Git log 的規(guī)范，也無法直接將 Git log 導出一個良好的 changelog。因為 changelog 中描述的內容需要更加精煉和歸納，對信息降噪處理等等，因此手寫 changelog 仍然是更好的選擇；當然，不排除以后自動轉換的可能。 不管是手寫還是自動轉換，changelog 的格式都不能直接照搬 Git log 的格式。這兩者的區(qū)別與聯(lián)系同在。

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 即項目的每一個發(fā)布版所使用的版本號。版本號需遵循 SemVer 版本號命名規(guī)范。

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

另外，版本號建議增加一個鏈接，指向當前版本和上一個版本之間的 diff。詳情可參考后文的樣本示例。

date

發(fā)布時間 date 即版本發(fā)布時的所在日期。

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

示例：

// good 2016-01-01 // bad 2016-1-1 20160101

type

更新類型 type 用以說明更新的方面。這里的 type 和 Git 提交日志中的 type 有所聯(lián)系，然而并不一一對應。

同前面提到的「標題」部分，默認使用中文版本的詞匯，如果是面向國際的項目，則使用括號中的英文版本。

type 的可選值如下：

新增（Features）：新增功能。 修復（Fixed）：修復 bug。 變更（Changed）：對于某些已存在功能所發(fā)生的邏輯變化。 優(yōu)化（Refactored）：性能或結構上的優(yōu)化，并未帶來功能的邏輯變化。 即將刪除（Deprecated）：不建議使用 / 在以后的版本中即將刪除的功能。 刪除（Removed）：已刪除的功能。

desc

描述內容 desc 需要注意：

使用完整的句子。即在標點方面遵循一般的文檔格式規(guī)范；如果使用英語，則句首大寫。 時態(tài)方面使用一般現在時，不要用過去時態(tài)。雖然查看 changelog 時，changelog 內容本身都發(fā)生在過去，然而使用現在時的時態(tài)更簡潔明確，并且更易達成一致性。 句式使用祈使句式。即一般情況不要增加主語。因為在絕大情況下，主語都是作者「我」。 注明修復的問題。如有提過 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`，以兼容傳統(tǒng) KIMI 的 node 對象擴展機制。 * ua 模塊現在可以識別 Microsoft Edge 瀏覽器。 ### 優(yōu)化 * `KISSY.getScript()` 從 loader 模塊中獨立出來，io 模塊不再依賴 loader 模塊。 ### 已刪除 * io 模塊默認去掉了對 XML 的 converter 支持。

參考資料

Keep a CHANGELOG The Discussion about Change Log 更新日志格式規(guī)范

相關知識

《范志紅·7日減肥餐單·夏秋特輯》更新完結啦！
醫(yī)療服務價格新規(guī)范來了，居民看病付費將更明白
《智慧健康美容服務規(guī)范》團體標準正式發(fā)布
辦健康證的證明格式及范文
GSMA啟動生成式AI移動終端需求規(guī)范，開啟智能手機新時代
健康證明格式參考范文6篇.doc
糖尿病規(guī)范注射日
互聯(lián)網廣告新規(guī)5月起施行，直播帶貨和醫(yī)藥保健廣告將更規(guī)范
辦理健康證介紹信格式范文
新版《通用規(guī)范漢字筆順規(guī)范》正式實施，替代1997年版

網址: CHANGELOG.md(更新日志)格式規(guī)范 http://m.u1s5d6.cn/newsview1313749.html