[譯] 為 GitHub 專案做出貢獻的初學者指南

goooooooogle發表於2019-03-02
Github

這是一個針對於如何在 GitHub 上貢獻開原始碼的新手指南。該指南主要基於我看到 Zend Framework，Slim Framework 和 joind.in 它們如何操作。但是，這僅僅是一個通用的指南，因此請先檢查專案的 README 檔案以瞭解具體情況。

第 1 步：在你的計算機上設定工作副本

首先你需要這個專案的本地克隆，所以先在 GitHub 中按下“fork”按鈕。按下按鈕後會自動在你的 GitHub 賬戶中建立一個該專案倉庫的副本，而且你會看到在已經被 fork 成功的專案名稱下面有一行註釋：

Forked

現在你需要一個本地副本，因此在右側列中找到“SSH clone URL”，並使用它在本地終端進行克隆：

$ git clone git@github.com:akrabat/zend-validator.git
複製程式碼

如下圖所示：

Clone

轉到新專案所在目錄中去：

$ cd zend-validator
複製程式碼

最後，在這個階段，你需要設定一個指向原始專案的新遠端地址，以便你可以抓取原始專案的任何更改並將它們更新至本地副本。首先定位到原始專案的連結 —— 它在 GitHub 頁面的頂部，通過“fork from”標記。該連結會將你帶回原始專案的 GitHub 主頁，因此你可以在該頁面找到“SSH clone URL”，並使用它去建立新的遠端，我們稱之為 upstream。

$ git remote add upstream git@github.com:zendframework/zend-validator.git
複製程式碼

你現在在磁碟上擁兩個此專案的遠端：

  1. origin：它指向你 fork 的 GitHub 專案。你可以向該遠端提交和拉取更新。
  2. upstream：你只能從這個上游的遠端拉取程式碼更新，而無法對其進行修改。

第 2 步：開始做出貢獻吧

這是你為專案作出貢獻時最有趣的一步。通常情況下，最好從修復一個令人討厭的 bug 開始，或者是你在專案的 issue 跟蹤器中找到的問題。如果你正在尋找一個開始的地方，很多專案使用“easy pick“標籤（或者相近意思的標籤）來表明這個問題可以由剛剛接觸此專案的人來解決。

分支

第一法則是將每一份修改工作都放到自己的分支上。如果專案使用 git-flow，那麼它將同時擁有一個 master 和一個 develop 分支。一般的規則是，如果你是修復 bug，那麼從 master 上拉下新分支。如果你正在新增一個新功能，那麼從 develop 上拉下新分支。如果該專案只有一個 master 分支，直接從該 master 拉取新分支。有一些專案，如 Slim 使用以版本號命名的分支（2.x 和 3.x）。在這種情況下，選擇相關的分支。

對於這個例子，我們假設我們正在修復 zend-validator 中的一個 bug， 所以我們從 master 拉出新分支：

$ git checkout master
$ git pull upstream master && git push origin master
$ git checkout -b hotfix/readme-update
複製程式碼

首先，我們要確保我們在 master 分支上。然後 git pull 命令將我們的本地副本與上游專案同步，並且 git push 命令將它同步到我們所在分支的 GitHub 副本專案中。最後我們建立我們的新分支。你可以根據你的喜好命名你的分支，但是它最好是有意義的。比如分支名中包含 issue 的編號一般很有益處。如果該專案像 zend-validator 一樣使用 git-flow，那麼在特定的命名約定中分支名的字首是“hotfix/”或者“feature/”。

現在你就可以開始做你的工作了。

確保你只修復你正在處理的事情。不要試圖解決你修復問題過程中看到的其他問題，包括格式問題，因為你的 PR 可能會被拒絕。

確保你在邏輯塊中提交。每次提交的備註（commit message）應該清晰說明改動的內容。請閱讀 Tim Pope 的關於 Git 提交訊息的注意事項。

第 3 步：建立 PR

要建立 PR，你需要將你的分支推送到 origin 遠端，然後按下 GitHub 上的一些按鈕。

推送一個新分支：

$ git push -u origin hotfix/readme-update
複製程式碼

這樣做將會在你的 GitHub 專案上建立新分支。-u 標誌符表示將本地分支與遠端分支相連，以便將來只需輸入 git push origin 就可以推送到遠端分支。

返回瀏覽器並導航到你 fork 的專案（在我的示例中地址是：https://github.com/akrabat/zend-validator），你會發現你的新分支在頂部列出了一個簡便的“Compare & pull request”按鈕：

Pr button

繼續然後按下按鈕！

如果你看到這樣的黃色框：

Contributing

點選連結可以將你帶到專案的 CONTRIBUTING 檔案並且你需要閱讀它！它包含有關如何使用該專案程式碼庫的寶貴資訊，並將幫助你如何使你的貢獻被接受。

在此頁面上，確保“base fork”指向正確的倉庫和分支。然後確保你為 pull request 提供了一個很好，簡潔的標題，並在說明框中解釋你為什麼建立了它。如果你有相關的 issue 編號，請新增進去。

Create pr

如果你向下滾動一點，你就會看到你的更改與原版本的差異。仔細檢查它是否是你想要的結果。

要是你覺得沒什麼問題了，按下“Create pull request”按鈕即可完成。

第 4 步：由維護人員審查

為了將你的修改工作整合到專案中，維護人員將檢查你的修改工作，並請求更改或合併它。

Lorna Mitchell 的文章程式碼審查：在你執行程式碼之前涵蓋了維護人員將要查詢的內容，所以閱讀它並確保不給維護人員增添麻煩。

總結

以上就是全部流程了。基礎步驟如下：

  1. Fork 原專案並克隆到本地。
  2. 建立一個 upstream 遠端並在你建立分支之前同步更新到你的本地副本。
  3. 為每項單獨的工作建立分支。
  4. 做好你的工作，編寫良好的提交資訊，並閱讀CONTRIBUTING檔案（如果有的話）。
  5. 推送到 origin 倉庫。
  6. 在 GitHub 中建立一個新的 PR。
  7. 迴應每一條程式碼審查的反饋資訊。

如果你想為一個開源專案做貢獻，最好的選擇就是你正在使用的某個專案。專案的維護者會很感謝你的！

如果發現譯文存在錯誤或其他需要改進的地方，歡迎到 掘金翻譯計劃 對譯文進行修改並 PR，也可獲得相應獎勵積分。文章開頭的 本文永久連結 即為本文在 GitHub 上的 MarkDown 連結。

掘金翻譯計劃 是一個翻譯優質網際網路技術文章的社群，文章來源為 掘金 上的英文分享文章。內容覆蓋 Android、iOS、前端、後端、區塊鏈、產品、設計、人工智慧等領域，想要檢視更多優質譯文請持續關注 掘金翻譯計劃、官方微博、知乎專欄。

相關文章