如何向開源專案做貢獻(以 incubator-dubbo 為例)
Github 上有眾多優秀的開源專案，大多數 IT 從業者將其當做了予取予求的工具庫，遇到什麼需求，先去 Github 搜一把，但有沒有想過有一天自己也可以給開源事業做一些貢獻呢？本文將會以 incubator-dubbo 專案為例，向你闡釋，給開源專案做貢獻並不是一件難事。
1 為何要給開源貢獻力量
為開源專案做貢獻得到的收益是多方面的，為了讓你有足夠的信心加入到開源專案中，我在文章最開始列舉出它的諸多好處。
1.1 鞏固技能
無論你是提交程式碼，撰寫文件，提交 Issue，組織活動，當你切身參與到一個開源專案中，相關的技能都會得到歷練，並且在開源專案中找到自己的位置。一方面，日常工作中我們中的大多數人接觸到的是業務場景，並沒有太多機會接觸到基礎架構元件，開源專案為我們提供了一個平臺，在這裡，你可以盡情挑選自己熟悉的專案為它添磚加瓦（以 Dubbo 為例，並不是所有 IT 公司都有能力自研服務治理框架）；另一方面，你所提交的程式碼，會有管理員協助稽核，他們會給出專業的建議，更好的程式碼規範以及更優的程式設計思路最終都會變成你的經驗。
1.2 結交朋友
開源社群為你提供了一個平臺，在這裡，你可以認識很多純粹的技術愛好者，開源貢獻者是最符合 geek 定義的那群人，你所接觸到的往往是某個領域最厲害的那批人。
1.3 建立口碑
這是一個很好的展示個人實力的地方，俗話說：talk is cheap，show me the code. 作為技術人員，沒有什麼比一個漂亮的 Github 主頁更有說服力的了。如果你能夠為開源專案做出可觀的貢獻，你也將收穫到業界的知名度，此時開源專案的成就和你是密不可分的。
1.4 傳承開源精神
只有源源不斷的貢獻者給開源專案添磚加瓦，才可以為 Github 一類的開源社群形成良好的開源風氣。否則，只有輸出沒有輸入，開源會失去活力。
1.5 養成習慣
相信我，一旦養成了每天提交程式碼的習慣，就像你不想中斷打卡一樣，你絕不想中斷 commit。不止有英語打卡，健身打卡，還有開源打卡！
2 貢獻程式碼時的一些疑難雜症
如果你是一名開源界的新手，可能會對貢獻的流程心生畏懼。比如：我該怎麼修改程式碼並提交？我的程式碼要是存在bug怎麼辦？我的程式碼別人會不會很 low？我該如何尋找合適的開源專案？開源社群那麼多的工具和詞彙都是什麼意思？
文章的第二部分將從一個 小白 的角度，介紹一下開源中的一些常見問題。
2.1 git 常規操作
一般而言，我們選擇使用 git 來作為版本管理的工具，你不一定要非常熟練的使用它，在我看來掌握 clone，add，commit，pull，push 即可，遇到複雜的場景，你還有谷歌。
fork 與 clone
如果你只是想下載原始碼，檢視他的原始碼實現，使用 Clone or download 按鈕即可。
如果你想要給開源專案做改動，並且最終請求合併，讓開源專案存在你貢獻的程式碼，就應該使用 fork。
fork 將會複製一份當前主分支的程式碼進入到你的倉庫中，之後你所有的修改，應當基於自己的倉庫進行，在功能開發/bug 修復之後，可以使用你的倉庫向源倉庫提交 pull request。只有源倉庫的管理員才有權利合併你的請求。
一些可能對你有幫助的高階指令。
# 設定源倉庫 git remote add upstream https://github.com/apache/incubator-dubbo.git # 拉取源倉庫的更新 git fetch upstream # 將自己倉庫的主分支合併源倉庫的更新 git checkout master git merge upstream/master 複製程式碼
pull request
pull request 經常被縮寫為 PR，指的是一次向源倉庫請求合併的行為，如上是我 fork 了 incubator-dubbo 的倉庫之後才存在的操作按鈕。
源倉庫視角的 pull request
管理者會對 pull request 涉及的改動進行 review，以確保你的程式碼是符合規範的，邏輯有沒有偏差，以及符合框架的功能需求。
2.2 Travis CI
一些自動化的 CI 流程被植入在每一次 pull request 的構建之中，用於給開源倉庫去校驗提交者的程式碼是否符合既定的規範，如：是否有編譯問題，單元測試是否通過，覆蓋率是否達標，程式碼風格是否合規等等。
一般情況下，必須通過 CI，你的 pull request 才會被管理 review。
2.3 Mailing list
每個開源專案都會有自己的貢獻規範，可以參考首頁的 Contributing，來獲取具體的資訊。incubator-dubbo 作為一個孵化中的 apache 專案，遵守了 apache 的傳統，在 Contributing 中描述道：當你有新特性想要貢獻給 Dubbo 時，官方推薦使用 Mailing list 的方式描述一遍你想要做的改動。
Mailing list 簡單來說，就是一個郵件通知機制，所有的 Dubbo 開發者都會訂閱該郵箱：[email protected]。有任何新特性的改動，或者什麼建議想要通知其他開發者，都可以通過向該郵箱傳送郵件來達到這個目的，相同地，你也會收到其轉發的其他開發者的郵件。
或者你是一個 Dubbo 的使用者，你想要得知開發者的改造方向，也可以訂閱，這個 指南 可以幫助你訂閱 Dubbo 的 Mailing list。
作為一個 modern developer，你可能覺得 mailing list 的交流方式存在滯後性，這樣的溝通方式不是特別的高效，但它作為 apache 專案的推薦交流方式存在其特殊的原因，在此不多贅述。總之遵循一個原則：bug fix或者討論，可以在 github issue 中進行，影響較大的特性和討論則推薦在 mailing list 中展開。
3 其他貢獻形式
不僅僅只有貢獻程式碼，修復 bug 等行為才算作為開源做貢獻，以下這些行為也屬於主要形式：
3.1 撰寫文件
Dubbo文件是其開源組成成分的重要一環，其內容原始檔位於： github.com/apache/incu… Git 倉庫，任何你想要對 dubbo 知識點的補充，都可以在這兒提交 pull request，只需要一些 markdown 的語法知識，和一些可有可無的 npm 語法即可。如果你覺得貢獻程式碼對於現在的自己仍然有點難度，不妨從貢獻文件開始接觸開源。
3.2 ISSUE
無論是 Github 中的 Issue 還是 mailing list 中的討論，無論是提出問題，彙報 bug，還是回答問題（bugfix 則不僅僅需要 Issue 了），協助管理者 review pull request，都是貢獻的一種形式，勿以善小而不為。
3.3 其他行為
任何你能夠想到的，可以幫助開源專案變得更好的的行為，都屬於開源貢獻。例如，給每個 Issue 打上合適的 tag，關閉重複的 Issue，連結相關聯的 Issue，線下組織沙龍，回答 Stack Overflow 上相關的問題，以及文件中一個錯別字的修改等等。
4 開源最佳實踐
4.1 有效溝通
無論你處於什麼樣的目的：僅僅是一次性的貢獻，亦或是永久性的加入社群，都的和他人進行溝通和交往，這是你要在開源圈發展必須修煉的技能。
在你開啟一個isse或PR之前，或者是在聊天室問問題之前，請牢記下面所列出的幾點建議，會讓你的工作更加的高效。
給出上下文以便於讓其他人能夠快速的理解。比方說你執行程式時遇到一個錯誤，要解釋你是如何做的，並描述如何才能再現錯誤現象。又比方說你是提交一個新的想法，要解釋你為什麼這麼想，對於專案有用處嗎（不僅僅是隻有你！）
:innocent: “當我做 Y 的時候 X 不能工作”
:cry: “X 出問題! 請修復它。”
在進一步行動前，做好準備工作。不知道沒關係，但是要展現你嘗試過、努力過。在尋求幫助之前，請確認閱讀了專案的 README、文件、問題（開放的和關閉的）、郵件列表，並搜尋了網路。當你表現出很強烈的求知慾的時候，人們是非常欣賞這點的，會很樂意的幫助你。
:innocent: “我不確定 X 是如何實現的，我查閱了相關的幫助文件，然而毫無所獲。”
:cry: “我該怎麼做 X ?”
保持請求內容短小而直接。正如傳送一份郵件，每一次的貢獻，無論是多麼的簡單，都是需要他人去查閱的。很多專案都是請求的人多，提供幫助的人少。相信我，保持簡潔，你能得到他人幫助的機會會大大的增加。
:innocent: “我很樂意寫 API 教程。”
:cry: ” 有一天我駕駛汽車行駛在高速公路上，在某個加油站加油的時候，突發奇想，我們應該這麼做，不過在我進一步解釋之前，我先和大家展示一下。。。”
讓所有的溝通都是在公開場合下進行。哪怕是很不起眼的小事，也不要去給維護者發私信，除非是你要分享一些敏感資訊（諸如安全問題或嚴重的過失）。你若能夠保持談話是公開的，很多人可以你們交換的意見中學習和受益。
:innocent: (評論) “@維護者 你好！我們該如何處理這個PR？”
:cry: (郵件) “你好，非常抱歉給發信，但是我實在很希望你能看一下我提交的PR。”
大膽的提問（但是要謹慎！）。每個人參與社群，開始的時候都是新手，哪怕是非常有經驗的貢獻者也一樣，在剛進入一個新的專案的時候，也是新手。出於同樣的原因,甚至長期維護人員並不總是熟悉一個專案的每一部分。給他們同樣的耐心,你也會得到同樣的回報。
:innocent: “感謝查看了這個錯誤，我按照您的建議做了，這是輸出結果。”
:cry: “你為什麼不修復我的問題？這難道不是你的專案嗎？”
尊重社群的決定。你的想法可能會和社群的優先順序、願景等有差異，他們可能對於你的想法提供了反饋和最後的決定的理由，這時你應該去積極的討論，並尋求妥協的辦法，維護者必須慎重的考慮你的想法。但是如果你實在是不能同意社群的做法，你可以堅持自己！保持自己的分支，或者另起爐灶。
:innocent: “你不能支援我的用例，我蠻失望，但是你的解釋僅僅是對一小部分使用者起作用，我理解是為什麼。感謝你的耐心傾聽。”
:cry: “你為什麼不支援我的用例？這是不可接受的！”
以上幾點，要銘記在心。開源是由來自世界各地的人們共同協作實現的。面臨的問題是跨語言、跨文化、不同的地理為止、不同的時區，另外，撰寫文字的溝通更是難上加難，無法傳達語氣和情緒。請讓這些會話都充滿善意吧！在以下情形中請保持禮貌：推動一個想法、請求更多的上下文、進一步澄清你的立場。既然你在網際網路找到了自己的所需，那麼請嘗試讓它變得更好！
4.2 建立 issue
你應該在遇到下列情況下，去建立一個 issue：
- 報告你自己無法解決的錯誤
- 討論一個高階主題或想法
- 期望實現某新的特性，或者其它專案的想法
在 issue 的溝通中幾點實用的技巧:
- 如果你剛好看到一個開放的issue，恰是你打算解決的， 新增評論，告訴他人你將對此展開工作，並及時響應。這樣的話，可以避免他人重複勞動。
- 如果說某個issue已經開放很久了， 這可能是已經有人正在解決中，又或者是早已經解決過了，所以也請新增評論，在打算開始工作之前，最好是確認一下。
- 如果你建立了一個issue，但是沒多久自己解決了， 也要新增評論，讓其他人知道，然後關閉該issue。記錄本身就是對社群的貢獻。
4.3 建立 pull request
在下面的情形時，請你務必使用 PR：
- 提交補丁 (例如，糾正拼寫錯誤、損壞的連結、或者是其它較明顯的錯誤）
- 開始一項別人請求的任務，或者是過去在issue中早就討論過的
一個 PR 並不代表著工作已經完成。它通常是儘早的開啟一個PR，是為了其他人可以觀看或者給作者反饋意見。只需要在子標題標記為“WIP”（正在進行中）。作者可以在後面新增很多評論。
如果說專案是託管在 GitHub上的，以下是我們總結出的提交RP的建議：
- Fork 程式碼倉庫 並克隆到本地，在本地的倉庫配置“上游”為遠端倉庫。這樣你可以在提交你的PR時保持和“上游”同步，會減少很多解決衝突的時間。(更多關於同步的說明，請參考 這裡 .)
- 建立一個分支 用於自己編輯。
- 參考任何相關的issue 或者在你的RP中支援文件(比如. “Closes #37.”)
- 包含之前和之後的快照 如果你的改動是包含了不同的 HTML/CSS。在你的PR中拖拉相應的圖片。
- 測試你的改動！ 若測試用例存在的話，跑一遍，以覆蓋你的更改，若沒有的話，則建立相應的用例。無論測試是否存在，一定要確保你的改動不會破壞掉現有的專案。
- 和專案現有的風格保持一致 盡你最大的努力，這也就是意味著在使用縮排、分號、以及註釋很可能和你自己的風格大相徑庭，但是為了節省維護者的精力，以及未來他人更好的理解和維護，還請你容忍一下。
5 成為一個開源貢獻者
如果你有志於參與開源事業，可以嘗試從自己最熟悉的專案開始，開源並不是屬於高階開發者的專屬詞彙，它就是由你我這樣的人在需求，修復，構建中演進下去的。Let's try it !
參考資料 如何為開源做貢獻
歡迎關注我的微信公眾號：「Kirito的技術分享」，關於文章的任何疑問都會得到回覆，帶來更多 Java 相關的技術分享。
