【譯】如何爲開源軟件作出貢獻

原文： How to Contribute to Open Source Software
做者：Matt Eland
譯者：博軒
爲保證文章的可讀性，本文采用意譯，轉載請保留原文連接

前段時間參加了2020年1月11日Node party線下分享，justjavac 大佬分享的主題就是：《如何融入並貢獻開源》（相關PPT，以及連接），感觸頗多。今天又看到一篇講關於如何參與開源的文章，就想翻譯下，與你們分享~

原文地址

若是你和我同樣，但願爲開源軟件作出貢獻，又不敢將第一個 pull request 發送至其餘團隊的代碼倉庫。

在本文中，我將與你們分享我第一次使用一個主流開源項目的經歷。我但願，這將有助於消除使用另外一個團隊代碼工做所帶來的恐慌的情緒，並向您展現在更大的社區中工做是多麼酷的一件事。

在本文中，我想專門和你們聊聊關於一個 Microsoft’s .NET 文檔項目 的 pull request。文中所提到的工做流程、工具和示例是該團隊，以及參與維護該項目團隊特有的，可是普遍的概念應該會適用於你遇到的許多項目。

尋找一個要貢獻的項目

毋庸置疑，爲了作出貢獻，您須要選擇一個想要貢獻的項目。

上週末，當我得知我已被.NET基金會錄取。這對於一個微軟死忠粉(從2001年開始就是.NET粉絲)來講是一件大事，這讓我想要找到一種方式，來爲任何與.NET相關的任何事情作出更多貢獻。

碰巧，我在Twitter上發現了一個帖子，激起了個人興趣：

我決定採納他們的建議，並查閱.NET文檔項目。畢竟，寫技術問題對我來講只是一件小事。

選擇你的第一個優秀的 Issue

一旦你選擇好了一個存儲庫，你須要找到一種開始的方式。

有時候，你會對一些須要改變的問題有強烈的的見解。其餘時候，你可能只是但願幫助團隊解決一個煊赫一時的 issue。

若是您試圖貢獻一些特定的內容，您能夠跳過本節的大部份內容，轉而實際使用代碼。也就是說，若是您所作的不是修復一個輸入錯誤或讓示例代碼正確編譯，那麼您確實應該在他們的存儲庫中爲您將要進行的工做建立一個 issue。這能夠確保您的工做是須要的，而且存儲庫全部者能夠在您爲這個主題花時間以前對其實現進行評論。

若是您不知道要處理什麼，請轉到存儲庫的 Issue 選項卡，查看全部可用的標記（tags）。想要查看當前開放的問題，並具備「良好的第一個問題」、「可供獲取」或應用於這些問題的相似標記。

微軟的文檔團隊已經對他們積壓的全部內容進行了完全的審查和評論，對於我來講，找到可用的問題簡直易如反掌。

如今，您須要找到一個問題，它不只看起來像是您感興趣的工做內容，並且對新接觸存儲庫的人來講很容易完成。

在個人例子中，我選擇了對c#和VB . net中的INotifyPropertyChanged示例的改進。原有的代碼很好，可是 .NET 隨着時間的推移而發展，而且隨着它的發展，出現了更好的實現方式。這是我在本身擅長的領域分享最佳實踐的機會，因此我抓住了這個機會。

理解 Issue

當你發現一個現存的問題時，你須要仔細和完全地閱讀它的描述以及它歷史上的每一條評論。存儲庫全部者和問題建立者可能在某種程度上已經加入進來，出於對他們代碼的尊重，您應該瞭解問題及其解決方式的意圖和關注點。

在個人例子中，.NET 文檔團隊很是典型，他們已經完全審查並討論了這個問題，我仍然有一些很是有用的意見可供參考。

我還發表了一篇評論，聲明瞭我在這個問題上的工做意圖以及我打算作出的改變。在必定程度上是爲了看看團隊是否會將問題從新分配給我，或者讓我從新當成另外一個問題來處理，可是沒有獲得回覆。

Fork 和 Clone 代碼倉庫

雖然您能夠在本地 Clone 存儲庫而無需 Fork ，可是除非您首先 Fork 了存儲庫，不然您將沒法發出 pull request。

值得慶幸的是，Forking 十分簡單。只須要點擊 GitHub 上的「Fork」按鈕，它就會引導你建立一個該存儲庫的副本。

存儲庫 Fork 以後，按照 GitHub 的提示將 Fork 的存儲庫克隆到您的機器上。

GitKraken 是我很是喜歡的一個 Git 客戶端，因此我複製了這個 URL 並使用這個 URL 從 GitKraken 克隆了出來，你也能夠選擇更適合你的方式，好比命令行或者其餘的應用程序。

理解團隊的工做流程

下一步將根據項目和團隊的不一樣而有所不一樣。首先，您須要肯定應該基於哪一個分支進行更改。接下來，您須要瞭解團隊是否選擇並專門化了 Git 工做流以及其分支的命名約定。

值得慶幸的是，在大多數存儲庫中你都不須要感到疑惑，由於社區已經規範了對於 contributing.md 和 readme.md 文件的建立， 它將指導您如何開始使用存儲庫，包括分支結構和 Git 工做流。

若是沒有相關的文檔就要當心了，由於團隊可能不歡迎新的貢獻者。

在個人例子中，.NET 文檔團隊提供了一個很是有用的貢獻指南，可是您可能不知道。您可能須要經過查看過去的提交來推斷事情，以肯定模式，甚至親自聯繫存儲庫全部者。

在開始使用編輯器以前，我建議在 git 中根據適當的開始分支建立一個分支(參見前面的討論)。必定要檢查以前的分支，以及 contributing.md 和 readme.md
文檔中關於分支命名的描述。

分支名稱並非沒有意義的，由於稍後您將向另外一個存儲庫提交 pull request，使用一致的分支名稱會幫助你提高歸屬感。

自我定位

好了，如今您已經在本地獲取了代碼，您能夠在任何編輯器中打開項目，以便處理需求。

在個人例子中，這個編輯器應該是 Visual Studio，可是我在存儲庫的根目錄下找不到 .sln 文件，因此我斷定這個項目應該是使用 Visual Studio Code 工做區。

我很高興地在 Visual Studio Code 中打開文件夾，獲得一個提示，當前工做空間與一組推薦的擴展相關聯，並詢問我是否要安裝它們。固然，我接受了這一點，而且 Visual Studio Code 以一種相似於維護者看待代碼的方式完成了自我配置。

您不太可能與像Microsoft文檔團隊這樣優秀的團隊一塊兒工做(若是您這樣作，我相信他們會很樂意聽到他們能夠改進的地方)。

即便有了這些有用的指導，你仍須要以你本身的方式來理解項目結構。而 contributing.md 可能有助於理解某些文件夾，一般我在項目中的第一步就是打開文件夾和子文件夾，直到我開始看到重複的組織模式。

一旦我熟悉了項目結構，我就開始尋找與我將要更改的代碼相關的文件。

在個人例子中，微軟經過在GitHub上的問題中標註它們，再次讓事情變得很是簡單。

所以，對於每一個問題，我查找了 how-to-implement-property-change-notifications.md，並查看了markdown文件中包含要更新的代碼示例的部分。

使人驚訝的是：

它沒有引用包含示例的頁面，而是引用了團隊維護的另外一個git存儲庫中的示例:樣例存儲庫。

這有點困難，由於我必須 fork 並 clone 那個倉庫，而後在項目的結構中找的我要查找的文件。

---

對我來講，第二個儲存庫是整個體驗中最大的負面因素。嵌套的存儲庫設計使我更難肯定本身的方向，也更難對本身正在作的事情有信心，由於我不能輕易地看到修改後的更改的標記。

我相信微軟這樣設計是爲了讓那些想要下載樣例並在本地使用它們的開發人員更加容易，因此團隊爲了更大的社區的利益犧牲了他們本身的生產力。

作出修改並測試

一旦你有了正確的答案，你須要作必要的修正或加強，測試它，而後提交修改後的文件。

構建代碼、運行測試、運行 linters (若是適用的話)，以及其餘方式驗證您的代碼都是很是重要的，這是在更大的社區中，成爲一個負責任的軟件工程師的很是重要部分。

值得慶幸的是，大多數大型項目都在提交請求過程當中內置了自動檢查，這將確保您的代碼符合團隊標準，可是在建立 pull request 以前，確保您的代碼在本地可以正常工做，這就避免了一些麻煩。

一旦提交了代碼，請確保將其推送到了存儲庫的 forked 版本。爲了建立 pull request ，這一步是必要的。

建立你的 Pull Request

如今，你已經推送了你的更改，你能夠回到你的 forked 倉庫 ，並經過點擊適當的提示來建立 pull request。

左側的分支和存儲庫表明要合併到的目標分支和存儲庫。這個存儲庫應該是項目的主存儲庫，分支一般與您的所在分支相同。右邊的分支和存儲庫將是您剛纔使用的
forked 存儲庫及其分支。

如今您已經設定了目標，接下來按照團隊的約定爲您的請求命名。在個人示例中，我將提交的描述性標題和問題編號放在括號中。

團隊還使用模板自動填充 pull request 主體的內容，我使用 markdown 語法編寫了一個詳細的更改列表。

注意，最後一行是 Fixed dotnet/docs#10675 。

這是 GitHub 解析的一個神奇字符串，它將個人提交與文檔庫中的正確問題(#10675)關聯起來(回想一下，我對 示例庫 作了更改)。

若是您對將什麼放入正在處理的存儲庫的 pull request 有任何顧慮，請花一些時間查看過去的 pull request 、它們的內容以及關於這些請求的任何註釋。

準備好以後，單擊 Create pull request。

接下來會發生什麼？

祝賀您，您爲開源軟件社區作出了一點貢獻。然而，這一旅程並無結束。

您的代碼可能須要經過自動檢查(一般是一個構建，也多是一些代碼分析)，而後才能進行評審。此外，項目維護者將須要檢查您的更改，並經過將它們合併到源存儲庫中來選擇是否接受它們。

在個人狀況下，更改在次日早上進行了審覈，我收到了一條友好的消息和一個通知，個人 pull request 被接受了，問題也解決了。

我所作的更改在那一天內就生效了，這意味着在我 fork 他們的存儲庫、進行更改，以及對這些更改進行審查、批准和部署到生產環境之間甚至沒有24小時。

總結

正如我所說的，我是微軟的死忠粉。然而，當我收到這條信息時，我並無預料的那麼自豪。這是個人提出的一個很小的改變，這個改變是團隊使得我很容易完成，可是我爲我所關心的事情作出了一點貢獻，這讓我感到很是自豪。

我強烈建議您嘗試一下爲開源軟件作貢獻。找一個你關心的項目，或者感興趣的東西。若是你找不到任何東西，試着像我同樣使用微軟的文檔，或者在Twitter上發佈一些東西，說你正在尋找一些須要幫助的項目。

從小事作起，看看事情是如何發展的，而後逐步發展成你喜歡的樣子。

社區是偉大的，若是你遵照他們的規範，代碼和工做流程，這一般會對他們產生很是大的幫助，並感謝你提供的幫助——即便你的代碼或註釋並不完美。

開發開源軟件是很是了不得的。它所須要的只是您的一點幫助。