用commitizen寫出angularjs風格的源代碼提交歷史
你的項目中是怎么寫提交歷史的?
不論你是用SVN、GIT或是其他源代碼倉庫,去看看實際項目中的提交歷史吧,你是否能很快地從中找到之前某一次的改動嗎?
看看這張圖中的提交歷史,眼熟嗎?
這還算是不錯的呢,還有很多項目的提交歷史根本就是大段空白!很多程序員其實并不清楚為什么要寫 提交歷史(commit messge) 。
早年間,提交歷史是直接寫在源代碼第一頁的注釋里面的,標明何時何人改動了什么內容,便于后人維護的時候來理解、定位、評審、追溯。
后來有了更好用的源代碼版本倉庫,于是這些內容就需要在每次提交時候寫上。歷史不能修改,也不能后補,發生了就發生了。
提交歷史是給人讀的,所以一定要考慮可讀性、準確性、完整性,并且通過關鍵詞便于后期查找。每一次提交只做一件事情,是寫出好的提交歷史的關鍵。
Angular.js開源項目如何編寫提交歷史
Angular.js 是著名的開源項目,看看人家提交 提交歷史規范 。
每條提交歷史包含 題頭、主體、腳注 三部分,而題頭又分為 類型、范圍、主題 三部分。
< 類型 >(< 范圍 >): < 主題 > <-空白行-> < 主體 > <-空白行-> < 腳注 >
類型(Type)
必須是下列中的一種:
- feat: 新功能(feature)
- fix: 修復缺陷
- docs: 僅文檔更新
- style: 不影響代碼含義的變更,如空格、格式化、漏掉分號等
- refactor: 重構,并未修復缺陷或添加功能
- perf: 性能(performance)提升
- test: 補充測試用例
- chore: 改進構建過程或輔助工具,例如文檔生成工具
范圍(scope)
指定修改的位置和范圍,如包名、類名、函數名等。非必填,但是建議填。
主題(subject)
描述變更的內容。
- 使用現在時態的祈使句,如”change”,但不要寫”changed”或”changes”。對于中文那就是”修改xxx”而不要寫”修改了xxx”
- 英文首字母不要大寫
- 結尾不用寫句號(.或。)
主體(body)
主體的風格與主題部分一致,用于詳細描述本次變更的動機,以及與上次提交差異。
腳注(footer)
腳注應該包含關于 破壞性變更 的信息,以及所關閉的任務ID,如github issue或JIRA-ID。
破壞性變更需要以 BREAKING CHANGE: 作為開頭,后面接1個空格或2個空行。
回滾(Revert)
如果需要撤銷之前的Commit,那么本次Commit Message中必須以 revert: 開頭,后面緊跟要撤銷那次提交的題頭部分,格式不變。主體則必須要記錄撤銷那次提交版本號。
用Commitizen命令行工具來增強git
Commitizen 是2015年4月出現在Github上的開源項目,用于增強git命令行,使人們能方便的寫出如angular.js項目般的提交歷史,還可以直接將這些提交歷史導出為發布說明(change log)。
(SVN用戶自己想辦法吧,其實也可以在commit hook里做文章)
安裝
npm install -g commitizen
配置打開項目執行如下命令:
commitizen init cz-conventional-changelog --save --save-exact
使用
在需要 git commit 的地方更換成 git cz 指令即可呼出Commitizen的交互界面,跟著提示做即可。
來自: http://www.jackyshen.com/2016/01/15/write-angularjs-style-commit-message-with-commitizen/