開發

如何為開源軟件做出貢獻

廣告
廣告

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

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

社區是偉大的,如果你遵守他們的規范,代碼和工作流程,這通常會對他們產生非常大的幫助,并感謝你提供的幫助——即使你的代碼或注釋并不完美。

我還沒有學會寫個人說明!

我經歷的全球移動辦公 297 天。

上一篇

TCP之 流量控制與擁塞控制

下一篇

你也可能喜歡

如何為開源軟件做出貢獻

長按儲存圖像,分享給朋友

ITPUB 每周精要將以郵件的形式發放至您的郵箱


微信掃一掃

微信掃一掃
篮球比分雷速直播网