完全初學者
從工具、術語和一個只改文件的變更開始。目標是完成一次安全閉環。
貢獻者指南
如何交付你的第一個 pull request
從找到適合初學者的議題到合併一個維護者可審查 pull request 的最短可靠路徑。
從這裡開始
選擇你的起點
把這些卡片當作靜態選擇器。選擇最符合目前狀態的一項，然後按下面相同階段推進。
第一次 PR
選擇一個很小且近期的議題，保持 diff 聚焦。編碼前先確認範圍。
再次貢獻者
把這套流程當作清單，然後把主要精力放在重現和測試修復上。
階段 0
安裝基礎工具
你只需要足夠的本地工具來 clone 倉庫、建立分支、執行專案檢查並推送工作。
git
Git 追蹤你的工作，並讓維護者準確審查改了什麼。
git --versiongh
GitHub CLI 幫助你在終端完成 fork、clone、認證和建立 pull request。
gh auth login
gh repo fork OWNER/REPO --clone --remoteeditor
使用能全倉搜尋、執行格式化並清楚展示變更檔案的編輯器。
code .階段 1
選擇合適的議題
好的 first issue 不只是小。它要新、可理解，並且可由專案維護者審查。
好信號
- 議題較新，或有維護者回覆。
- 倉庫設定說明仍然可用。
- 預期改動能放進一個小 pull request。
- 描述了測試或手動驗證步驟。
警示信號
- 已有多人在做同一個議題。
- 議題模糊、陳舊，或被設計討論阻塞。
- 改動涉及安全、計費、資料庫遷移或發布自動化。
- 專案近期沒有維護者活動。
判斷路徑
- 你能用一句話說明這個請求嗎？
- 你能在本地重現或驗證問題嗎？
- 改動能保持小且獨立嗎？
- 如果三項都是 yes，就詢問是否可以接手。
階段 2
6 步流程
保持流程簡單可預期。小 pull request 更容易審查、修正和合併。
認領議題
留下簡短評論，說明具體議題並詢問目前範圍是否仍然合理。
閱讀規則
改程式碼前閱讀 CONTRIBUTING、README、開放 PR、測試命令和程式碼風格說明。
Fork + 分支
建立自己的副本，並用和任務相關的分支工作，不要直接在 main 上改。
設定 + 重現
安裝依賴、重現問題，並記錄你看到問題的命令或頁面。
交付小 diff
只改必要程式碼。避免順手重構、升級依賴和無關格式化。
開啟 PR
說明改了什麼、如何測試，以及任何限制。讓審查者的第一遍審查更輕鬆。
gh repo fork OWNER/REPO --clone --remote
cd REPO
git checkout -b docs/fix-install-note
pnpm install
pnpm test
git status
gh pr create --fill模板
可複製模板
根據實際情況調整措辭，保持具體，不要承諾超出你能完成的範圍。
認領評論
你好！我想處理這個 issue。
我的計畫是把改動範圍控制在：
- ...
在開始前，這個方向是否合適？PR 描述
## 改動內容
- ...
## 如何測試
- ...
## 備註
- 這是我對該倉庫的第一次貢獻，歡迎回饋。暫停點
繼續投入前的警示信號
盡早停止，比強行提交無法審查的 pull request 更好。
- 按文件設定後仍無法在本地執行專案。
- 修復需要在沒有維護者輸入的情況下猜測產品行為。
- 議題要求大功能、重設計、遷移或架構決策。
- 維護者已說明首次貢獻者不要處理該區域。
參考
術語表
- Fork
- 你的個人倉庫副本。開啟 pull request 前，你會把分支推送到這裡。
- Branch
- 一條可移動的工作線。每個議題使用一個分支，改動更容易審查。
- Pull request
- 請求維護者審查並把你的分支合併到專案倉庫。
- Diff
- 解決議題所需的最小有意義改動集合，不包含無關清理。
- CONTRIBUTING
- 專案特定的設定、風格、測試和 pull request 期望清單。
FAQ
常見第一次 PR 問題
維護者一週沒回覆怎麼辦？
用簡短跟進說明目前狀態並提出一個直接問題。如果仍沒有回覆，換一個議題，不要無限等待。
設定失敗時我該怎麼辦？
說明你嘗試了什麼，貼出準確錯誤，附上作業系統和工具版本，並詢問下一步除錯方向。
我的第一個 PR 可以只改文件嗎？
可以，前提是倉庫歡迎文件改動。清楚文件、範例、錯字和壞鏈修復都是真正的貢獻。
第一次合併之後
把一次貢獻變成可重複的習慣
感謝審查者，記錄有效命令，保存專案慣例，然後尋找只比上一個稍難一點的下一個議題。