小學(xué)老師說(shuō)：好腦子不如爛筆頭

前言

作為一個(gè)普通的開(kāi)發(fā)者，我必須為我的項(xiàng)目維護(hù)一個(gè)更新日志（以下簡(jiǎn)稱 changelog）嗎？

如果你在維護(hù)一個(gè)開(kāi)源項(xiàng)目，或者公司內(nèi)部的底層技術(shù)產(chǎn)品，那么提供一個(gè) changelog 是必需的。開(kāi)發(fā)者用戶很可能需要從一個(gè)低版本升級(jí)到最新版，changelog 可以幫助他們了解新版本有哪些變化。 如果你在開(kāi)發(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ī)范，也無(wú)法直接將 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ó)際通則，以下再闡釋一番：

使用大寫來(lái)表明本文件的重要性，相當(dāng)于是項(xiàng)目倉(cāng)庫(kù)元信息的一部分。 使用 .md 作為后綴，而不是 .txt 或干脆不加后綴。使用標(biāo)準(zhǔn) Markdown 語(yǔ)法，從而可以方便地渲染。

基本的 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 用以說(shuō)明更新的方面。這里的 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)化，并未帶來(lái)功能的邏輯變化。 即將刪除（Deprecated）：不建議使用 / 在以后的版本中即將刪除的功能。 刪除（Removed）：已刪除的功能。

desc

描述內(nèi)容 desc 需要注意：

使用完整的句子。即在標(biāo)點(diǎn)方面遵循一般的文檔格式規(guī)范；如果使用英語(yǔ)，則句首大寫。 時(shí)態(tài)方面使用一般現(xiàn)在時(shí)，不要用過(guò)去時(shí)態(tài)。雖然查看 changelog 時(shí)，changelog 內(nèi)容本身都發(fā)生在過(guò)去，然而使用現(xiàn)在時(shí)的時(shí)態(tài)更簡(jiǎn)潔明確，并且更易達(dá)成一致性。 句式使用祈使句式。即一般情況不要增加主語(yǔ)。因?yàn)樵诮^大情況下，主語(yǔ)都是作者「我」。 注明修復(fù)的問(wèn)題。如有提過(guò) 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)信息的問(wèn)題。 ## [6.2.3] - 2015-11-16 ### 修復(fù) * 修復(fù) `KISSY.getScript` 在傳入了 `timeout` 參數(shù)后報(bào)錯(cuò)的問(wèn)題。[#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ú)立出來(lái)，io 模塊不再依賴 loader 模塊。 ### 已刪除 * io 模塊默認(rèn)去掉了對(duì) XML 的 converter 支持。

參考資料

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

相關(guān)知識(shí)

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

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