# Git Commit Message 規範 為了維持專案歷史紀錄的可讀性與追蹤效率，本團隊採用以下 Commit 規範。撰寫訊息時應兼具「做了什麼（What）」以及「為什麼做（Why）」，讓日後進行維護人員更快進入狀況。 ## 1. 訊息格式 ```text <動作 action>: <標題 title> <敘述 description> (選填) fixed <issue 編號> (若為修復 Issue 則必填) ``` ## 2. 動作類型 (Action) 請根據 Commit 的性質選擇正確的動作標籤： | 動作 (Action) | 說明 | | --- | --- | | **feat** | 新增或修改功能（對使用者/外部行為有新增或變更） | | **fix** | 修補 Bug（修正錯誤行為、例外、邏輯缺陷） | | **docs** | 僅文件更動（README / 註解 / 文件，不改程式行為） | | **style** | 只改格式（lint/排版/縮排/換行），不得改邏輯 | | **refactor** | 重構（不改外部行為，但改善結構/抽象/可維護性） | | **perf** | 效能改善（降低耗時/記憶體/查詢次數等） | | **test** | 新增或修改測試（單元/整合/e2e） | | **chore** | 工具/依賴/CI/建置腳本調整（不影響產品功能） | | **revert** | 撤銷/回退先前的 Commit | ## 3. 欄位定義 ![圖片](https://hackmd.io/_uploads/ryZt4Ia_bl.png) ### 標題 (Title) (Header) * **必填**(建議不要超過 50 個字元) * 結尾不加句號。 * 精簡描述本次更動的核心內容。 ### 敘述 (Description) (Body) * **選填**，當標題無法完全說明改動細節時使用，對本次 Commit 的詳細描述，可以分成多行。 * 應包含： * 為什麼要進行此項更動？ * 解決了什麼問題？ * 調整了哪些主要項目？ * 建議每一行不要超過 72 個字元。 ### 腳部 (Footer) * **非必填(有修復 issue 時必填)**，但若該 Commit 是為了修復特定的 Issue 或任務，則必須附上。 * 格式：`fixed <issue 編號>` * 例如：如果是修復bugtrace測試人員提出的問題任務，修復完成的Commit需要再下面附上該問題單的編號，(例如：`fixed 0000006`)。 ![圖片](https://hackmd.io/_uploads/S1g6Q-BTOZx.png) ## 4. 範例參考 ### feat (新功能) ```text feat: 新增使用者大頭貼上傳功能 原因：使用者希望在個人頁展示頭像以提升辨識度 調整： - 新增 /api/users/avatar 上傳端點 - 上傳後將檔案存至 S3，回傳可公開存取的 URL - 前端新增預覽與上傳進度顯示 ``` ### fix (修補 Bug) 情境：離開提醒邏輯 ```text fix: 修正表單頁離開時誤觸未保存提醒 問題： - 新增頁面未輸入內容直接離開仍跳提醒 - 從編輯頁返回列表後，離開列表也會誤跳提醒 原因：初始化時誤將表單標記為 dirty，且返回列表時未解除 unload 監聽 調整： - dirty 狀態改為「使用者實際輸入」才設為 true - 於路由切換/元件銷毀時確實移除 unload 事件監聽 fixed 1335 ``` 情境：信件圖片權限 ```text fix: 修正意見反應信件無法顯示附件圖片 原因：附件路由要求登入驗證，導致 email client 無法存取圖片 調整：意見反應上傳的檔案改為公開讀取（仍保留上傳限制與檔案類型檢查） fixed 1229 ``` ### chore (建構程序與輔助工具) ```text chore: 升級 phpunit 至 0.17 原因：0.16 無法支援 Request GET 帶參數的測試情境 調整：更新相依版本並修正 CI 中的測試指令參數 ``` （調整測試結構 + 修 issue） ```text chore: 調整測試目錄結構並統一後台登入測試基底 調整： - 新增 tests/unit 與 tests/integration 目錄以區分測試層級 - 新增 AdminTestCase 作為共用登入流程與初始化 fixed 709 ``` ### style (格式調整) 情境：統一換行符號 ```text style: 統一換行符號為 LF 調整：將專案檔案換行由 CRLF 統一為 LF，避免跨平台 diff 噪音 ``` ### docs (文件更新範例) ```text docs: 更新部署手冊，補充 Docker 環境參數說明 新增： - .env 必填/選填參數表 - 本機與 CI 的範例設定 ``` ### refactor (重構，不改外部行為) ```text refactor: 抽離 API 呼叫共用處理至 utils 原因：多個模組重複處理 token、錯誤轉換與 retry，導致維護成本高 調整： - 將 request 包裝、錯誤 mapping、重試策略集中到 utils - 保持原 API 介面與回傳格式不變（無功能行為變更） ``` --- ## 5. 撰寫原則 (Best Practices) 1. **獨立提交**：不應一次 Commit 所有異動，應根據意義獨立提交。 2. **清楚明瞭**：讓未參與該段程式開發的人也能透過訊息快速理解改動目的。 3. **不要當成 FTP**：Git 是歷史查閱工具，請不要只寫「update」、「save」等無意義訊息。 參考資料：Git Commit Message 這樣寫會更好，替專案引入規範與範例 [https://ithelp.ithome.com.tw/articles/10228738]