---
# System prepended metadata

title: Commit規範
tags: [Commit規範, Git]

---

# 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]