CI/CD Server Note 02
良好的Commit Message提升團隊協作效率。
Git Commit Message 規範與範例
Commit Message不僅僅是一串文字，它還代表了程式開發過程中的一個里程碑，承載著開發者在這次提交中所做的工作和更改。好的Commit Message有助於團隊成員更好地理解程式碼變更的目的和內容，讓其他夥伴或是接手專案的人更容易上手，所以要寫下為什麼要做這樣的異動，而不是只單純的紀錄做了什麼樣的更動。
所以為了促進專案內部的溝通協作，可以考慮制定一些規範，確保每個成員都能在程式碼的變更中保持一致的理解。如選用清晰的語言描述變更、提供相關的Issue或需求編號以便追溯、避免過於冗長或過於簡略的描述等。
這些細節可能在初期看似微不足道，但隨著專案的成長和發展，這些訊息可以讓你日後需要回顧更改的內容時，能更快速且精確的找到問題點，確保了專案健康和可維護性的關鍵要素。
優化Commit Message提升團隊協作效率
在 2014 年 Chris Beams 寫過一篇 How to Write a Git Commit Message提及了重要的七大點:
- 將訊息用空白斷行區分標題與內容
- 標題限制在 50 字元以內
- 標題開頭使用大寫
- 標題不以句點結尾
- 使用祈使句設計標題
- 內容每行最多 72 字，過多文字則需要斷行
- 內容需解釋 what 以及 why vs. how
這七點不一定是必要遵守的規範，重點是要讓Commit Message具有統一的規則，而相同的風格可以較容易閱讀程式碼。
以下提供幾個概念讓每個Commit Message更容易閱讀，從而提高程式碼的可維護性和合作效率:
- 清晰簡潔的描述：用關鍵詞描述這個提交所執行的類型（修復、新增、更新），不要一次commit所有更動的程式碼，應該要獨立commit不同意義的每個異動，簡潔地敘述這次提交的主要內容。
- 上下文：提供適當的上下文，記錄對更動的程式碼的說明，以及它對程式碼或專案的影響，這樣可以讓日後維護的人員更快進入狀況。
- 避免縮寫、技術術語：盡量使用通用的術語，而不是過於專業的術語或縮寫，除非是普遍被接受且易於理解的，保持易讀性。
- 一致的格式：保持Commit Message格式一致且易讀，例如使用類型的場景、類型的Emoji等，提高信息傳達的清晰度。
- 分段落描述：如果變更涉及不同方面，可以使用分段落的方式來詳細描述每個方面的變更。
- 引用問題：如果這次變更是為了解決特定的問題或工作項目，引用相關issue或項目編號，這樣可以方便追蹤原因。
一個 Commit Message基本的框架主要由 Header + Body + Footer 組成，以下是Commit Message的撰寫規範：
Header: <type>(<scope>): <subject>
- type (必要欄位):
代表 commit 的類別：
feat, fix, docs, style, refactor, test, chore等等
- scope (可選欄位):
代表 commit 影響的範圍
例如資料庫、控制層、模板層等等，視專案不同而不同
- subject (必要欄位):
代表此 commit 的簡短描述
不要超過 50 個字元，結尾不要加句號
Body: 72-character wrapped. This should answer:
* Body 部份是對本次 Commit 的詳細描述
可以分成多行，每一行不要超過 72 個字元
* 說明程式碼變動的項目與原因，還有與先前行為的對比
* 盡量讓Commit單一化，一次只更動一個主題
Footer:
- 填寫任務編號（就像是issue編號，如果有的話）
- BREAKING CHANGE:
通常有一些不相容等級的改動，或是這個改動需要有別人配合著修改才能正常運作的改動
則需要特別用 BREAKING CHANGE 來註明
並且在底下詳細說明不相容的部分，影響的模塊/範圍，然後對應的修改/配合方式
常見的Commit Message類型建議
遵循一些常見的Commit Message類型可以幫助團隊成員更容易理解代碼變更的目的和內容，以下是一些常見的Commit Message類型建議：
| type | description |
|---|---|
| init | 初次提交/初始化專案 |
| feat | 新增/修改功能 (feature) |
| fix | 修補bug (bug fix) |
| docs | 添加/更新文檔，完善專案說明 (documentation) |
| style | 程式碼風格變更，例如格式調整，不影響程式碼運行 |
| refactor | 不影響既有的功能前提下，改進程式碼的結構、可讀性和維護性 |
| perf | 增進效能、修復效能問題、新增效能優化 (增加快取) |
| test | 涉及測試方面的更改，如新增/修改測試案例 |
| chore | 建置環境或輔助工具/套件的變動 (保持程式碼的健康和可讀性，不直接影響代碼的功能) |
| revert | 撤銷回復先前的commit (標記撤銷操作，讓團隊成員更容易了解變更的背景和原因) |
Git Commit Message使用Emoji
在Git Commit Message中使用Emoji可以帶來一些好處，讓團隊成員更容易理解你的提交，並促進更好的協作和溝通，以下是一些在Git Commit Message中使用Emoji的好處：
- 清晰的表達意圖： Emoji 可以在一個小圖片中傳達情感、主題或操作的意圖。這可以幫助團隊成員更快速地理解提交的目的，而無需閱讀完整的提交消息。
- 增強可讀性：使用特定的 emoji 可以幫助區分不同類型的提交。例如，使用 🐛 表示錯誤修復，使用 ✨ 表示新增功能，這有助於快速識別提交的目的。
- 引起關注： 良好選擇的 emoji 可以使提交在提交歷史中更加突出，從而更容易引起團隊成員的注意使提交歷史更有趣，也更易於快速掃視。
儘管使用Emoji可以帶來這些好處，仍然需要適度使用避免過度使用Emoji，並確保配以足夠的文字說明解釋更改的細節，以免讓提交訊息變得混亂或難以理解，以下是要注意的一些點:
- 專業性問題： 在某些專業環境中，使用 Emoji 可能被視為不正式，特別是當處理嚴肅的程式碼更改或與客戶合作時。
- 過度使用： 過多地使用 emoji 可能會導致提交消息變得混亂且難以理解，從而降低了其效益。
Emoji 可以是一個有趣且有用的方式使提交歷史更加生動有趣，但使用時需要謹慎和適度，根據你的團隊文化和項目需求選擇是否在提交消息中使用 Emoji，若要使用一定要建立明確的使用準則，並確保在整個團隊中保持一致性。
以下是使用Emoji的一些範例:
| type | Emoji | description |
|---|---|---|
| init | 🎉 | 初次提交/初始化專案 |
| feat | ✨ | 新增/修改功能 (feature) |
| fix | 🐛 | 修補bug (bug fix) |
| docs | 📝 | 添加/更新文檔，完善專案說明 (documentation) |
| style | 💄 | 程式碼風格變更，例如格式調整，不影響程式碼運行 |
| refactor | ♻️ | 不影響既有的功能前提下，改進程式碼的結構、可讀性和維護性 |
| perf | 👌 | 增進效能、修復效能問題、新增效能優化 (增加快取) |
| test | ✅ | 涉及測試方面的更改，如新增/修改測試案例 |
| chore | 🛠️ | 建置環境或輔助工具/套件的變動 (保持程式碼的健康和可讀性，不直接影響代碼的功能) |
| revert | ↩️ | 撤銷回復先前的commit (標記撤銷操作，讓團隊成員更容易了解變更的背景和原因) |
Commit Message範例
在撰寫Commit Message 時，可以參照AngularJS的規範:
feat範例
feat: 摘要
因應需求做調整：
1. 調整項目
調整項目：
1. 影響到的程式
issue #編號
fix範例
fix: 摘要
問題：
1. 問題說明
原因：
1. 造成這個問題的原因說明
調整項目：
1. 做了什麼更動
issue #編號perf範例
perf:
調整方式:
結果:
時間 XX 秒 => X秒
issue #編號
結論
當開發團隊能夠對Commit Message的內容和使用時機達成一致共識時，就能夠建立起優良的Commit Message，有助於將來的程式碼維護工作大幅簡化，使開發人員專注於核心開發任務，不被瑣碎的版本控制細節所分心。隨專案演進，可導入自動化的工具來協助生成Commit Message，減少手動輸入的同時，提高一致性和資訊豐富度。
Commit Message不僅是版本控制工具的一部分，也是團隊協作和知識傳承橋樑。透過建立良好的Commit Message範例，開發團隊可以更有效地協作、更輕鬆地應對專案的各個階段，從而提升整體的開發品質和效率，為專案奠定堅實的基礎。
參考資料
NG-ZORRO