本篇重點
- Reference System 透過簡單的語法讓 Issue、Pull Request、Commit 建立關聯
- 同一個 Repository 內的所有 Issue 和 PR 共用同一組遞增的流水號
- 跨儲存庫參照使用
owner/repo#number - 支援文字輸入的 GitHub 介面，皆可解析並觸發參照語法
- 雙向追蹤機制自動建立雙向提交紀錄和通知
- 利用
Closing Keywords關閉 issue
在多人協作的專案中，Issue、Pull Request、Commit 常常是彼此相關的，如果只依靠網址或文字描述，這樣閱讀成本較高，也很難追蹤整個開發流程。
GitHub 提供的 Reference System（參照系統），可以透過簡單的語法建立不同物件之間的關聯，讓 Issue、Pull Request、Commit 等內容彼此串聯。
PR 和 Issue 的關係
在 GitHub 的資料結構中，Pull Request（PR）與 Issue 被歸類為同類型的「溝通物件」，PR 在本質上可視為一個「夾帶了 Git 分支和變更紀錄的 Issue」，並且同一個儲存庫（Repository）內的所有 Issue 和 PR 共用同一組遞增的流水號。
此規則確保了編號的絕對唯一性，在單一專案中不會出現「Issue #5」與「PR #5」互相衝突的情況，兩者在系統底層對應的是同一個編號序列。
常見 Reference 語法
同一個 Repository
用於參照目前 Repository 中的 Issue 或 Pull Request，格式為 #number，範例：#123。
跨 Repository
用於參照其他 Repository 的 Issue 或 Pull Request，格式為 owner/repo#number，範例：python/project#123。
適合在多個 Repository 共同開發時建立關聯。
健忘筆記
如果目標 Repository 為 Private 或目前帳號沒有存取權限，GitHub 將無法建立有效的 Reference。
Commit
用於參照指定 Commit，格式為 owner/repo@sha，範例：facebook/react@a1b2c3d。
支援的參照場景
GitHub 參照系統的應用範圍廣泛，只要是支援文字輸入的 GitHub 介面，皆可解析並觸發參照語法。主要應用場景包含：
- Issue 與 PR 的內容與評論：用於串聯相關討論上下文，讓對話歷程更具追溯性。
- PR 的描述（Description）：設定變更請求的依賴目標，或提供相關背景資訊，方便程式碼審查者理解脈絡。
- Commit 訊息：在推送程式碼時，將參照直接寫入 Commit 訊息，讓單次變更與追蹤系統產生直接關聯。
雙向追蹤機制
參照功能不僅產生靜態的超連結，更具備系統層級的互動與自動化能力，形成完整的雙向追蹤：
- 自動建立 Referenced：當 Commit、Comment 或 Pull Request 參照某個 Issue 時，Issue 頁面會自動出現 Referenced 紀錄，方便追蹤有哪些開發工作與此 Issue 有關。
- 自動通知：被參照的 Issue 或 Pull Request 相關參與者，可能會收到 GitHub 的通知，提高協作效率。
- Closing Keywords：透過特定關鍵字（如
Fixes、Closes、Resolves等）關閉 issue，這些關鍵字除了可寫在 Pull Request Description，也能出現在 Commit Message。當變更合併至 Default Branch 後，GitHub 會自動關閉對應的 Issue。
專案參照範例
情境假設：在 project A 發現問題並建立 Issue，隨後於 project B 提交修正 PR，並透過 Closing Keywords 讓參照系統自動關閉 project A 的 Issue。
Step 1：建立 issue
在 project A 建立新的 Issue 描述問題，系統配發編號為 #1。
Step 2：開發與提交變更
在 project B 進行程式碼修正，並於 Commit 訊息中記錄關聯（change README forgetfulengineer/projectA#1）。
project A 的 issue 自動出現 Referenced 紀錄
Step 3：發起變更請求與狀態綁定
於 project B 建立 PR，並在 PR 描述區塊寫入 Closing Keywords 關鍵字： forgetfulengineer/projectA#1。
project A 的 issue 自動出現 Referenced 紀錄
Step 4：合併後自動觸發關閉
project B 的 PR 通過審查並執行 merge，系統自動觸發狀態同步。
project A 的 Issue #1 隨即自動轉換為 Closed 狀態。
參照語法總整理
| 參照目標類型 | 語法結構 | 情境說明 | 範例 |
|---|---|---|---|
| 同儲存庫 Issue/PR | #編號 | 建立當前專案關聯 | #123 |
| 跨儲存庫 Issue/PR | 擁有者/儲存庫#編號 | 建立跨專案關聯 | facebook/react#123 |
| 特定 Commit | 擁有者/儲存庫@雜湊值 | 建立專案特定程式碼變更紀錄 | facebook/react@a1b2c3d |
| Closing Keywords | Fixes #編號 | PR 合併時自動關閉關聯 Issue | Fixes #123 |
| User | @username | Mention 使用者 | @forgetful_engineer |
結論
GitHub Reference System 將 Issue、Pull Request、Commit 和 Repository 串聯成完整的協作紀錄，透過簡單的 Reference 語法和 Closing Keywords，能提升程式碼和需求的可追溯性，也能讓 Issue 的生命週期從建立、開發、Code Review 到 Merge 都保持清楚且一致，是 GitHub 協作中實用且不可或缺的重要功能！
