GitHub Issue 與 Git Commit 命名指南
更新日期： 2024 年 12 月 9 日
本文為 GitHub 操作指令教學，第 1 篇：
- GitHub Issue 與 Git Commit 命名指南 👈 所在位置
- Git Clone：初次複製專案的完整指南
- 使用 git fetch 與 git pull， 從 GitHub 取得最新檔案內容
- Git Ignore：排除檔案的完整指南
- 修改 Git 提交訊息與內容的完整指南
- GitHub 上傳檔案完整指南
- 發佈 Pull Request 與重新提交的完整指南
建議閱讀本文前，先閱讀完 Git 指令基本介紹教學 系列文
在使用 GitHub 和 Git 進行專案開發時，良好的命名習慣能提高協作效率，讓每個團隊成員能快速理解任務內容與版本歷史。
本文將介紹 GitHub Issue 的命名方式與 Git Commit 的格式，並提供常見的命名單字清單，幫助新手建立統一且清晰的命名規範。
什麼是 GitHub Issue
GitHub 的 Issue 追蹤系統是一種專案管理工具，用於記錄、追蹤和管理軟體開發過程中的各類事項，如錯誤（bug）、功能需求、技術債務和其他待辦事項。
透過 Issue，開發者和團隊成員可以：
- 報告錯誤：詳細描述問題，提供重現步驟和環境資訊，方便開發者理解並解決問題。
- 提出功能請求：提交新功能或改進建議，促進專案的持續優化。
- 任務分配：將特定 Issue 分配給相關人員，明確責任，提升協作效率。
- 追蹤進度：設定 Issue 的狀態（如待處理、進行中、已解決）和優先級，確保專案按計劃推進。
- 討論與協作：在 Issue 中留言討論，分享資訊，確保團隊成員對問題的理解一致。
此外，GitHub 的 Issue 系統還支援：
- 標籤（Labels）：為 Issue 添加標籤，分類管理，方便檢索和篩選。
- 里程碑（Milestones）：將相關 Issue 組織在一起，設定目標和截止日期，便於專案規劃。
- 關聯 Pull Requests：將 Issue 與 Pull Request 關聯，清楚了解程式碼變更與問題之間的關係。
透過這些功能，GitHub 的 Issue 追蹤系統為開發團隊提供了一個高效的協作平台，提升專案管理的透明度和可控性。
為什麼命名很重要？
- 提高可讀性
清晰的命名能讓團隊成員快速了解 Issue 的內容或提交的功能點。 - 統一格式
統一的格式讓專案更具條理性，方便追蹤和查詢。 - 便於過濾與篩選
使用標準化的單字能讓 GitHub 的搜尋與篩選功能發揮更大效用。
GitHub Issue 命名規範
在 GitHub Issue 的命名中，通常包含以下幾部分：
- 類型標籤：描述這個 Issue 的性質，如新增功能、修復 Bug 等。
- 簡短描述：清楚說明任務的核心內容。
命名格式
[類型] 簡短描述類型標籤常用單字
| 單字 | 用途 |
|---|---|
| feat | 新增功能 (feature)。 |
| fix | 修復問題或 Bug。 |
| modify | 修改現有內容，例如更新文件或調整功能。 |
| test | 增加或修改測試。 |
| refactor | 重構代碼，不改變功能。 |
| chore | 例行任務，如更新依賴項或工具配置。 |
| docs | 文件相關，例如更新 README 或說明文檔。 |
命名範例
根據附圖中的例子，這些命名方式可以幫助描述 Issue 的具體內容：
[modify] 增加 README.md 環境變數說明
表示修改文件，補充 README 的內容。[feat] 設計用戶角色切換邏輯
表示新增功能，實現角色切換的功能。[feat] 設計用戶模型
表示新增用戶相關的數據模型。[feat] 開發註冊功能
表示新增註冊功能。
Git Commit 命名規範
Git Commit 的命名應與 Issue 命名保持一致，讓開發者在版本歷史中快速理解提交內容。
推薦格式如下：
命名格式
[類型] 簡短描述命名單字
| 單字 | 用途 |
|---|---|
| feat | 新增功能。 |
| fix | 修復問題或錯誤。 |
| docs | 修改文件，如 README。 |
| style | 代碼風格調整，不影響功能 (如格式化)。 |
| refactor | 重構代碼，優化結構但不改變功能行為。 |
| perf | 提高性能的修改。 |
| test | 測試相關的變更。 |
| chore | 更新依賴、工具配置等雜務工作。 |
範例比較：GitHub Issue 與 Git Commit 的對應
| GitHub Issue | Git Commit |
|---|---|
[feat] 設計用戶角色切換邏輯 | [feat] 實現角色切換功能 |
[modify] 增加 README.md 環境變數說明 | [docs] 補充 README 環境變數文檔 |
[fix] 修正註冊功能無法儲存用戶資料 | [fix] 修正用戶資料儲存邏輯 |
[refactor] 重構數據處理邏輯 | [refactor] 優化數據處理模組結構 |
小結
透過統一的命名規範，團隊可以清楚了解每個 Issue 的內容與每次提交的目的，進一步提升專案的可讀性與協作效率。以下是本文的重點回顧：
- Issue 命名格式：
[類型] 簡短描述。 - Commit 命名格式：
[類型] 簡短描述，類型應與 Issue 對應。 - 常用類型單字：
feat、fix、docs、refactor等。
良好的命名習慣不僅能讓版本歷史更清晰，也能在團隊合作中建立更高效的開發流程！