第一次給開源項目提 PR 時，最容易產生的錯覺是：我必須做一件很大的事。實際上，我的第一個 PR 只修了一個文檔裡的命令、補了一段安裝說明，卻完整地經歷了一次協作流程。

這篇文章把那條軌跡拆開，留給下一次準備按下 “Create pull request” 的自己。

先讀貢獻指南

在 fork 之前，先花十分鐘看倉庫根目錄裡的 CONTRIBUTING.md、README.md 和最近的 issue。

重點確認四件事：

  • 項目是否接受文檔或小修復；
  • 提交信息和分支命名有沒有約定；
  • 代碼風格與測試命令是什麼；
  • 是否要求先開 issue 討論。

跳過這一步會省下十分鐘，然後在 review 裡花掉兩天。

fork、clone，再接上 upstream

在自己的 GitHub 賬號下 fork 項目，然後 clone 到本地：

git clone [email protected]:your-name/project.git
cd project
git remote add upstream https://github.com/original-owner/project.git

origin 指向你的 fork，upstream 指向原倉庫。之後每次開始工作前，先同步主分支：

git fetch upstream
git switch main
git merge --ff-only upstream/main

保持 fork 的主分支幹淨，可以少處理很多無關的合併提交。

讓改動只做一件事

我給那次 PR 改了兩處：一個失效的命令，以及緊接著的說明文字。沒有順手格式化整個文件，也沒有把另一個發現的問題塞進來。

一個小而完整的改動更容易被理解，也更容易被回滾。如果腦海裡冒出“順便把這裡也改一下”的念頭，先把它記成一條獨立的 issue。

提交前檢查差異：

git diff
git status

確認沒有編輯器生成的臨時文件，也沒有把個人配置帶進倉庫。

PR 描述是寫給未來的自己

一個可讀的 PR 描述通常包含三件事：

  • 為什麼改：問題是什麼，讀者會在哪裡卡住；
  • 改了什麼：用兩三句話說明範圍；
  • 如何驗證：運行了什麼命令，看到了什麼結果。

如果能附上一張截圖或一段終端輸出，reviewer 會輕鬆很多。禮貌不是客套，它是在降低別人理解你的成本。

merge 之後

PR 被合併並不代表結束。同步 upstream，刪除已經無用的分支，再開始下一次改動：

git fetch upstream
git switch main
git merge --ff-only upstream/main
git branch -d fix/install-command

如果 maintainer 提出了修改意見，不要把它理解成否定。開源協作的默認狀態是異步和有限注意力，清晰的回應比頻繁的道歉更有用。

軌跡比結果重要

第一個 PR 的規模並不重要。重要的是你第一次完整走過了一條協作路徑：從閱讀規則，到提交、回應、合併，再到清理。

下一次，你會知道該在哪裡停下確認，哪裡應該補一條測試，哪裡保持安靜。開源不是舞臺，它更像一張許多人一起維護的星圖。你補上的那一小段光，真實存在。