如何建立你的第一個開源 PR

Good First Issue,
contributorsopen-sourcepull-requests

第一次開源 pull request 的難點通常不是 Git、GitHub，或建立 PR 的操作本身。真正難的是選擇一個範圍小、仍然有效、容易理解，並且有機會得到維護者 review 的任務。

Good First Issue 正是圍繞這個判斷建立的。它協助你從「我想貢獻」走到「這個 Issue 很實際，倉庫仍然活躍，也有足夠脈絡讓我提交一個有用的 PR」。

從合適的 Issue 開始

先打開 Issues 頁面。用你熟悉的工具或技術關鍵字搜尋，按標籤或語言篩選，並透過排序避免從陳舊任務開始。

有用的入口包括：

不要把標籤當成保證。它只是起點。一個好的 first issue 仍然需要清楚範圍、活躍倉庫，以及足夠資訊讓你驗證修改。

像 reviewer 一樣閱讀 Issue

在 clone 之前，先打開 Issue 詳情頁，查看它是否值得投入時間。關注標籤、倉庫、主要語言、stars、評論、反應、負責人、描述和 GitHub 源連結。

然後再看 Contributor Guide 中繼資料。Good First Issue 會總結技術棧、領域、Issue 類型、難度、預估時間、活躍狀態、清晰度、前置條件、新手友善度和研究方向等訊號。

你要尋找這些匹配點：

  • Issue 描述說明了成功結果。
  • 倉庫近期仍有活動，review 有可能發生。
  • 所需技術棧接近你能在本機執行的範圍。
  • 討論裡沒有其他人已經深入處理同一個修復。
  • 研究方向給出了下一步，而不是模糊願望。

GitHub 始終是事實來源。Good First Issue 索引並總結公開資料，但資料可能過期。如果 Issue 已關閉、已分配，或被 GitHub 上新的維護者評論推翻，請以 GitHub 為準。

選擇很小的範圍

第一次 PR 要優先考慮可 review 性。維護者應該能在幾分鐘內打開 diff 並理解變更。

好的第一步通常像這樣：

  • 文件改進。
  • 能重現小型已知行為的測試。
  • 期望結果清楚的小 bug 修復。
  • 目標效果明顯的 UI 打磨。
  • 你能驗證的範例、README 或 setup 說明。

避免資料庫 migration、認證、安全行為、發布自動化、依賴策略、公開 API、大範圍產品功能或不清晰的產品決策。這些以後也可能是有價值的貢獻，但因為 review 面太大，通常不適合作為第一個 PR。

寫程式前先認領 Issue

當你有了小範圍計畫後，先在 GitHub Issue 留一條簡短評論。你不是在請求開源貢獻許可，而是在確認這個範圍是否仍符合維護者期待。

Hi! I would like to work on this as my first contribution to the project.

My plan is to update <small, specific area> by <brief change>. Does that scope still make sense?

If there is already a preferred approach, I am happy to follow it.

如果維護者回覆了建議，就按建議做。如果沒人回覆，但 Issue 明確 open 且無人分配，你也可以提交一個小而充分測試的 PR。保持 diff 狹窄，讓維護者容易說 yes、no，或「請調整這一部分」。

Fork、建分支、測試並打開 PR

確定範圍後，優先遵循倉庫自己的貢獻文件。如果沒有指定流程，通常下面這版已經足夠：

gh repo fork OWNER/REPO --clone
cd REPO
git checkout -b fix-small-specific-thing

# 使用專案文件指定的 package manager 安裝依賴。
<install command>

# 做解決 Issue 的最小修改。

# 打開 PR 前執行相關檢查。
<test command>

git status
git add <changed files>
git commit -m "fix: update small specific thing"
git push -u origin fix-small-specific-thing
gh pr create --fill

更完整的命令級流程可以參考 Contributor guide。

什麼樣的 PR 適合維護者 review

適合 review 的 PR 會說明改了什麼、怎麼測試，以及 reviewer 在看 diff 前需要知道的事項。你不需要寫長文，但需要提供足夠脈絡，避免 reviewer 只能從程式碼裡反推意圖。

## What changed

- Updated <area> so <behavior/result>.
- Kept the change limited to <scope>.

## How I tested

- Ran <command>.
- Manually checked <page, flow, or example>.

## Notes

- This addresses <issue link>.
- I am new to this repository, so feedback on the preferred style is welcome.

PR 打開後繼續關注維護者評論。用小的後續 commit 回應回饋，除非專案要求，否則避免 force push，並讓討論始終圍繞合併這個具體 Issue。

準備選擇下一次貢獻時，回到 issues 或瀏覽 repositories，重複同樣流程：先選擇活躍、可理解、可 review 的工作，再開始寫程式。