Git Commit Message 這樣寫會更好,替專案引入規範與範例

其實寫 Commit Message 有時候跟寫程式註解還蠻像的,
最好可以寫下「為什麼」你要作這樣的異動,
而不是單單只記錄下你做了「什麼」異動,
Commit Message 最好兼俱 Why 及 What,讓日後進行維護人員更快進入狀況。

Commit Message 這樣寫會更好:

  • 做 issue 的時候,不應該一次 Commit 所有異動!應該獨立 Commit 每個不同意義的異動,這樣 commit 訊息才會跟異動的程式碼有關聯。
  • 每次 Commit 都是針對異動的檔案做說明:Why & What。這樣的 Commit Message 能讓日後的維護人員更快進入狀況
  • 每次 Commit 都加上 issue 編號,方便追蹤相關的程式異動原因。
若 Commit Message 寫得妥當,在閱讀追蹤程式碼的意圖會相當容易。如果只把 Git 當作版本控制,隨意撰寫 Commit Message 就太可惜了!
不能只把 Git 當作程式碼的 FTP,這樣太可惜了,要把 Git 當作歷史查閱的工具才拿發揮 Git 的功能。

好與不好的真實案例

用一個小插曲證實 Commit 訊息的重要性
上面 PPT 是我在工作中遇到的兩個案例,範例中包含「好的 Commit Message」與「不良的 Commit Message」。
在範例中可見:
  • 良好的 Commit Message: 如何在「一年後」讓維護人員進入狀況
  • 不良的 Commit Message: 如何在「一個月內」讓維護人員找不出程式異動的原因

Commit Message 之規範

在撰寫 Git 與 SVN 等版本控制軟體 Commit Message 時,可以參照國外 AngularJS 團隊的規範: AngularJS Git Commit Message Conventions
以下為這套訊息規範的展示與說明:
Commit Message 規範範例:

Commit Message 規範範例解析:

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 個字元。
 * 說明程式碼變動的項目與原因,還有與先前行為的對比。

Footer: 
 - 填寫任務編號(如果有的話).
 - BREAKING CHANGE(可忽略),記錄不兼容的變動,
   以 BREAKING CHANGE: 開頭,後面是對變動的描述、以及變動原因和遷移方法。
type: subject 是簡述不要超過 50 個字元

type 只允許使用以下類別:

  • feat: 新增/修改功能 (feature)。
  • fix: 修補 bug (bug fix)。
  • docs: 文件 (documentation)。
  • style: 格式 (不影響程式碼運行的變動 white-space, formatting, missing semi colons, etc)。
  • refactor: 重構 (既不是新增功能,也不是修補 bug 的程式碼變動)。
  • perf: 改善效能 (A code change that improves performance)。
  • test: 增加測試 (when adding missing tests)。
  • chore: 建構程序或輔助工具的變動 (maintain)。
  • revert: 撤銷回覆先前的 commit 例如:revert: type(scope): subject (回覆版本:xxxx)。
Type 是用來告訴進行 Code Review 的人應該以什麼態度來檢視 Commit 內容。
例如:
  • 看到 Type 為 fix,進行 Code Review 的人就可以用「觀察 Commit 如何解決錯誤」的角度來閱讀程式碼。
  • 若是 refactor,則可以放輕鬆閱讀程式碼如何被重構,因為重構的本質是不會影響既有的功能。
利用不同的 Type 來決定進行 Code Review 檢視的角度,可以提升 Code Review 的速度。因此開發團隊應該要對這些 Type 的使用時機有一致的認同。

Commit 訊息範例

範例 fix:

fix: 自訂表單新增/編輯頁面,修正離開頁面提醒邏輯

問題:
1. 原程式碼進入新增頁面後,沒做任何動作之下,離開頁面會跳提醒
2. 原程式碼從新增/編輯頁面回到上一頁後(表單列表頁面),離開頁面會跳提醒

原因:
1. 新增頁面時,頁面自動建立空白題組會調用 sort_item,造成初始化 unload 事件處理器。
2. 回到上一頁後,就不需要監聽 unload 事件,應該把 unload 事件取消。

調整項目:
1. 初始化 unload 事件處理器:排除新增表單時,頁面自動建立空白題組調用 sort_item 的情境
2. 回到上一頁後,復原表單被異動狀態且清除 unload 事件處理器

issue #1335
fix: 意見反應,信件看不到圖片問題

問題:
1. 客戶反應:意見反應的信件都看不到圖片。

原因:
1. 目前程式碼都會要求先登入後才可查看使用者上傳的檔案,
   造成在信件上會看不見圖片的問題。

調整項目:
1. File.php,經討論後,開放讓意見反應頁面上傳的檔案,不用登入就可以查看/下載。

issue #1229

範例 feat:

feat: message 信件通知功能

因應新需求做調整:
 通知和 message 都要寄發每日信件,
 通知和 message 都用放在同一封信裡面就好,
 不然信件太多可能也不會有人想去看。

調整項目:
1. mail_template.php,新增 message 區塊。
2. Send_today_notify_mail.php,新增 取得每日 Message 邏輯。
3. Message_model_api.php,新增 $where 參數,以便取得每日訊息。
4. Message_api.php、Message_group_user_model_api.php,新增 **取得訊息使用者** 邏輯,以便撈取每日訊息。

issue #863
feat: 表單統計,多顯示計畫名稱欄位

因應需求做調整:
1. 列表資訊多加「計畫名稱」欄位,以利後續匯出資料處理。

調整項目:
1. Assessment_form.php,匯出表單統計時,新增訓練計畫名欄位。
2. customize.php,表單統計查詢時,多顯示訓練計畫名欄位。
3. Complex_assessment_form_api.php、Complex_assessment_form_model_api.php:
  - 取得表單統計資料時,多取得計畫名稱。

issue #1200

範例 chore:

chore: 更新 testing 環境

更新 ci-phpunit-test 套件 0.16 => 0.17

for Request GET 帶參數功能。
chore:調整單元測試環境

調整項目:
1. MX/Modules
將客製化 Testing 的邏輯移除,否則在測試環境中無法正確存取檔案。
2. 加入 tests/unit 與 tests/integration 目錄,並將測試檔案移至合宜的位置。
3. AdminTestCase.php,繼承 TestCase,實作登入邏輯、setUp 與 tearDown,供其他測試案例繼承使用。
4. Bootstrap.php,引入 AdminTestCase.php 共測試案例繼承用。
5. Login.php,因測試案例中不能有 header 的設定,更動系統登入邏輯,在測試環境中改用 redirect 轉址。
6. phpunit.xml,取消嚴謹宣告覆蓋模式,避免造成測試不通過(若需知道你的測試案例覆蓋了哪些類別或邏輯,可自行打開)。

## 備註: unit 與 integration 目錄
分別為「單元測試目錄」與「整合測試目錄」,單元測試目錄負責測試 Api 與 Model,整合測試目錄則負責測試 Controller。

issue #709

範例 style:

style: message 頁面,對 Component 做 Beautifier

經 IE 瀏覽器測試後發現 Component 裡面仍然夾帶 ES6 語法,
但是目前 Component 的程式碼都被壓縮成一行,
為了日後修改程式方便,故先對所有被壓縮的程式碼做 Beautifier

調整項目:
1. 針對所有被壓縮的程式碼做 Beautifier
2. 移除被註解的程式碼,原本被註解的程式碼應該是壓縮前的程式碼,但是經測試後發現這些被註解的程式碼都是舊 Code,故移除。

issue #1219
issue #1028
style: 統一換行符號 CRLF to LF

統一換行符號
style: 調整 HTML 縮排

issue #964

範例 refactor:

refactor: 重構取得「簽核流程種類名稱」邏輯

原程式碼取得流程名稱的邏輯散落在多個檔案,
為了讓未來新增/修改種類名稱時,不必到多個檔案找查程式,
現在統一透過 Process::get_type_name($process_type) 方法,
取得流程種類名稱。

調整項目:
1. Process.php,新增 get_type_name() 方法,供取得流程名稱稱用。
2. workflow_type_name.php,此 View 檔案只是為了取得流程名稱,現在以 Process:: get_type_name() 取代,故刪除。
3. Workflow_api.php,get_process_name() 方法是為了取得流程名稱,現在以 Process:: get_type_name() 取代,故刪除。
4. 其他檔案:改用 Process:: get_type_name()  取得流程名稱。

issue #1253
refactor: 表單統計,語意化調整

匯出表單時的表單答題資料,
應該是以表單 $assessment_result  為基準做統計,
故更改變數名稱 $user => $assessment_result

issue #1200
refactor: 每日通知信件,重構程式結構

考量將來可能會需要寄送多種資訊給使用者,
故重構程式結構,讓未來擴充功能時比較方便。

調整內容:
1. Send_today_notify_mail:
  - 把取得「系統通知」邏輯搬移至 System_notify_handler.php
  - 把取得「站內訊息」邏輯搬移至 Message_handler.php
  - 引入 Pipeline,把取得各種系統資訊的邏輯注入進 Pipeline。
  - 透過 Pipeline 取得每日通知信件內容,並建立信件 HTML
2. Daily_email 介面:
  - 定義 每日信件處理器 Xxx_handler 的方法
  - 之後要擴充新的功能,必須按照 Daily_email 介面的定義,實作方法。
3. message.php、system_notify.php:
  - 將「系統通知」與「站內訊息」的 Email 頁面獨立出來。

issue #1308

範例 perf:

perf: 評核表單列表,優化取得受評者速度

原本取得受評者的邏輯會造成載入頁面緩慢(開發機約 52 秒),故做優化。

調整方式:
原程式碼每個表單迴圈進入 DB 取得受評者資料。
改成
進 DB 一次撈取全部受評者資料,再回到 PHP 分配資料。

結果:
開發機載入頁面時間  52 秒 => 5秒

issue #1272

範例 docs:

docs: 新增註解
docs: 修正型別註解

讓 IDE 可以讀取到正確的類別
docs: 移除過期的註解

issue #1229

留言

  1. 範例完整 學習了
    謝謝
    總覺得 angular style 的 type 形式太少

    看到別人分享的有
    modify:功能上的修正(非 bug)
    change:功能或規格變更
    disable:拿掉某功能(comment out)
    remove:刪除檔案
    upgrade:版本更新

    但又覺得太多type種類,是否反而複雜

    回覆刪除
    回覆
    1. 首先要先知道 ,Type 其實是為了讓 Code Review 的人可以什麼態度來檢視 Commit 內容。

      例如看到 Type 為 fix,進行 Code Review 的人就可以用「觀察 Commit 如何解決錯誤」的角度來閱讀程式碼。

      若是 refactor,則可以放輕鬆閱讀程式碼如何被重構,因為重構的本質是不會影響既有的功能。

      利用不同的 Type 來決定進行 Code Review 檢視的角度,可以提升 Commit 的速度。

      您提及的 modify、change、disable、remove 其實都屬於 feat 的範疇,也就是「需求異動」。upgrade 則屬於 chore 的範疇「建置環境」。

      只要開發團隊能對這些 Type 有一致的認同以及使用時機,細分 Type 其實也沒什麼不好!但是我自己導入團隊的經驗是,光是 angular 的 Type 就已經很多工程師搞不清楚怎麼使用了 XD

      刪除

張貼留言