如何為開源軟體做出貢獻

如果你和我一樣，希望為開源軟體做出貢獻，又不敢將第一個 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上釋出一些東西，說你正在尋找一些需要幫助的專案。

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

社群是偉大的，如果你遵守他們的規範，程式碼和工作流程，這通常會對他們產生非常大的幫助，並感謝你提供的幫助——即使你的程式碼或註釋並不完美。