如何向開源項目作貢獻(以 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 開發者都會訂閱該郵箱：dev@dubbo.incubator.apache.org。有任何新特性的改動，或者什麼建議想要通知其餘開發者，均可以經過向該郵箱發送郵件來達到這個目的，相同地，你也會收到其轉發的其餘開發者的郵件。

或者你是一個 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以前，或者是在聊天室問問題以前，請牢記下面所列出的幾點建議，會讓你的工做更加的高效。

給出上下文 以便於讓其餘人可以快速的理解。比方說你運行程序時遇到一個錯誤，要解釋你是如何作的，並描述如何才能再現錯誤現象。又比方說你是提交一個新的想法，要解釋你爲何這麼想，對於項目有用處嗎（不只僅是隻有你！）

😇 「當我作 Y 的時候 X 不能工做」

😢 「X 出問題! 請修復它。」

在進一步行動前，作好準備工做。 不知道不要緊，可是要展示你嘗試過、努力過。在尋求幫助以前，請確認閱讀了項目的 README、文檔、問題（開放的和關閉的）、郵件列表，並搜索了網絡。當你表現出很強烈的求知慾的時候，人們是很是欣賞這點的，會很樂意的幫助你。

😇 「我不肯定 X 是如何實現的，我查閱了相關的幫助文檔，然而毫無所獲。」

😢 「我該怎麼作 X ?」

保持請求內容短小而直接。 正如發送一份郵件，每一次的貢獻，不管是多麼的簡單，都是須要他人去查閱的。不少項目都是請求的人多，提供幫助的人少。相信我，保持簡潔，你能獲得他人幫助的機會會大大的增長。

😇 「我很樂意寫 API 教程。」

😢 」 有一天我駕駛汽車行駛在高速公路上，在某個加油站加油的時候，突發奇想，咱們應該這麼作，不過在我進一步解釋以前，我先和你們展現一下。。。」

讓全部的溝通都是在公開場合下進行。 哪怕是很不起眼的小事，也不要去給維護者發私信，除非是你要分享一些敏感信息（諸如安全問題或嚴重的過失）。你若可以保持談話是公開的，不少人能夠大家交換的意見中學習和受益。

😇 (評論) 「@維護者 你好！咱們該如何處理這個PR？」

😢 (郵件) 「你好，很是抱歉給發信，可是我實在很但願你能看一下我提交的PR。」

大膽的提問（可是要謹慎！）。 每一個人參與社區，開始的時候都是新手，哪怕是很是有經驗的貢獻者也同樣，在剛進入一個新的項目的時候，也是新手。出於一樣的緣由,甚至長期維護人員並不老是熟悉一個項目的每一部分。給他們一樣的耐心,你也會獲得一樣的回報。

😇 「感謝查看了這個錯誤，我按照您的建議作了，這是輸出結果。」

😢 「你爲何不修復個人問題？這難道不是你的項目嗎？」

尊重社區的決定。 你的想法可能會和社區的優先級、願景等有差別，他們可能對於你的想法提供了反饋和最後的決定的理由，這時你應該去積極的討論，並尋求妥協的辦法，維護者必須慎重的考慮你的想法。可是若是你實在是不能贊成社區的作法，你能夠堅持本身！保持本身的分支，或者另起爐竈。

😇 「你不能支持個人用例，我蠻失望，可是你的解釋僅僅是對一小部分用戶起做用，我理解是爲何。感謝你的耐心傾聽。」

😢 「你爲何不支持個人用例？這是不可接受的！」

以上幾點，要銘記在心。 開源是由來自世界各地的人們共同協做實現的。面臨的問題是跨語言、跨文化、不一樣的地理爲止、不一樣的時區，另外，撰寫文字的溝通更是難上加難，沒法傳達語氣和情緒。請讓這些會話都充滿善意吧！在如下情形中請保持禮貌：推進一個想法、請求更多的上下文、進一步澄清你的立場。既然你在互聯網找到了本身的所需，那麼請嘗試讓它變得更好！

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 相關的技術分享。