零起點的開源社區貢獻指南

【開源社區貢獻者】聽起來是個專屬於頂級開發者的頭銜，但它真的有這麼高不可攀嗎？下面的分享旨在揭開它的神祕面紗，幫助感興趣的同窗更輕鬆地參與到社區項目中來。

首先須要澄清的是，本文做者本身並非社區高大上項目的原創做者，只是在一個 5k+ Star，100+ 貢獻者的項目中貢獻排名前十而已（做爲參考，Vue 的貢獻者不到 150 人），和《維護一個大型開源項目是怎樣的體驗》這個問題裏閃耀的羣星相比，只不過是個小透明的存在。不過由於本身也只有一年有餘的經驗，在不少方面上和剛剛入門的新人同窗們都很類似，所以相信我的經驗能有必定的參考價值，纔在此作了些總結。文中若有不妥之處，請 dalao 們斧正。

下文內容主要分爲這兩部分：

• 起步與進階，介紹在對編程一無所知的時候，可以經過什麼方式參與到社區中來。以及在有了貢獻的條件後，如何經過 Issue 和 PR 在開源項目中協做。
• 技巧與總結，介紹一些技術性的細節，以及如何在 Github 上商業互吹的溝通技巧。

起步

參與開源項目的主要方式，由易到難不外乎這三種：

• 翻譯文檔
• 報告 bug
• 提交代碼

在起步階段，翻譯文檔的難度無疑是最低的。由於這甚至不須要你編寫或運行任何代碼，只要在編輯頁面裏翻譯就足夠了。

以 Mozilla 維護的 MDN 文檔爲例，也許有很多同窗不知道，MDN 文檔和維基百科同樣，是容許全部用戶編輯的。好比，一篇介紹 CSS 定位方式的 MDN 文檔，頁面頂部大概長這樣：

mdn-large

注意到 Languages 和 Edit 了嗎？你能夠在 Languages 裏選擇你須要的語言，或者添加新語言的翻譯。若是已有翻譯，能夠直接點擊 Edit 編輯！

在翻譯時，Mozilla 的富文本編輯器會分爲左右兩個部分，能夠直接對照：

mdn-editor

如今只要點擊保存，你就會出如今這個頁面的貢獻者裏了！你的更改也會在文檔歷史中保存，因此在提交前不妨檢查下內容吧。另外，並非一次保存就必須搞定一整篇文檔，寫到一半準備保存的話，能夠點擊頁面最下方的 本地化進行中 選項，這樣就可以在瀏覽頁面中添加一個【翻譯正在進行中】的標識啦。

這個過程裏咱們彷佛一行代碼都沒有寫，那麼這有什麼用嗎？我的的觀點是，翻譯文檔是一個很好的開始，由於它能夠：

• 幫助你更好地理解英文技術文檔的行文結構，爲後面和其餘開發者的交流打好基礎。後面咱們也會說起，不少時候須要爲一兩行代碼編寫的文檔遠遠不止一兩行。
• 很大地鍛鍊你的行文水平。在初期你可能會寫出比較翻譯腔、不通順的技術文檔，熟悉之後會有很大的進步。
• 讓你的貢獻迅速地獲得反饋。MDN 的權重在 Google 並不低，經過 Google 在第一頁查到你翻譯的內容，仍是挺有成就感的。
• 提升你本身對文檔內容的瞭解。以做者本人爲例，在瞭解富文本編輯領域時首先就是從搬運 Mozilla 中的富文本編輯器文檔做爲開始，完成翻譯後就這個領域內的基礎概念瞭然於心了。

除了 MDN 文檔外，中文技術社區也有很多優秀的相關項目能夠參與。這方面我的的參與很少，就不班門弄斧了。

進階

只是翻譯文檔的話，你可能很快就會達到【寫膩了】的階段，這時候就不妨來看看更大的世界吧。找一個 Github 上的活躍項目做爲開始吧！對於在 Github 上維護的開源項目，主要的參與方式包括 Issue 和 PR 兩種：

Issue

對一箇中大規模的開源項目，Issue 主要用來：

• 報告 Bug 與提問
• 提出並討論新特性
• 設定 Todo 目標

須要注意的是，許多項目是有本身的 Discuz 論壇或 Slack 羣的，有一些相似【爲何安裝失敗了】的新手向問題能夠先在已有 Issue 中搜索，而後再在論壇和 IM 中提出。若是隨意地提出 Issue，極可能會獲得 Duplicate of #xxx 的回覆而後被關掉。對於新同窗，一個很是好的參考是《提問的藝術：如何快速得到答案》。

只要給項目提出過 Issue，你當天的 Github 貢獻圖就會刷綠，而且也可以把這個項目固定在我的主頁裏了！看起來一樣不須要寫代碼，並不難呀。不過，單純地提 Issue 並不會讓你出如今項目的貢獻者列表裏，若是想真正地【貢獻】代碼的話，PR 是必須的。

PR

Pull Request 顧名思義，就是請求別人拉取你的代碼的意思。這是十分符合開源工做流的：開發者們 fork 出本身的倉庫，在本身的 分支裏 commit 代碼，而後請求維護者將本身的更改合併進來。通常而言一個 PR 只要作好一件事情就足夠了，其做用不外乎如下之一：

• 修復 bug
• 實現新特性
• 優化性能
• 例行更新（如文檔、依賴版本等）

新同窗若是想要貢獻 PR，不妨先從本身擅長或關注的方面去着手，好比一些簡單的文檔拼寫錯誤，或者標記爲 help please 一類的 Issue。

只要提出 PR，不論合併與否當天的 Github 貢獻圖都會刷綠，而 PR 合併入主幹時，當天的貢獻圖也會刷綠。假設你發現了一個小 bug，只要一行就可以修復，那麼整個流程走下來大概是這樣：

1. 提出 Issue，貢獻 +1
2. 提出 PR，貢獻 +1
3. 回覆維護者的 Review 評審，貢獻 +1
4. PR 經過，貢獻 +1

因此，哪怕僅僅提交一行代碼，最多也足夠點綠四天的貢獻圖了。而且，維護者們在 Review 或併入你的 PR 時，他們的貢獻也會相應增長。這樣想來，大型項目貢獻者們一年動輒幾千的貢獻數量也不是隻能讓人仰望的了吧。

技巧

上面僅僅介紹了開源工做流中的幾個基礎概念。在真正參與時，還有一些能夠稍加註意的技巧。下面介紹的就是一些與此相關的小細節。

問題導向的源碼閱讀

在須要提出 bugfix、新 feature 或性能優化類 PR 的時候，閱讀框架源碼基本是繞不開的。固然，咱們常常可以在技術社區看到不少【源碼解析】類的文章（在近期以 Redux / Vue / Koa 爲甚）。做者寫這些文章的出發點確定是好的，不過使人有些遺憾的是，許多這類文章的閱讀量相對並不高，而且多數這類文章的做者並非這些框架的貢獻者。

是咱們太浮躁了嗎？咱們不妨從動機上考慮一下，咱們爲何須要閱讀源碼呢？是爲了解決實際遇到的問題，仍是僅僅爲了寫一篇博客來展現本身的技術水平呢？若是隻是貼上一個個看起來高大上的代碼截圖，而後把註釋翻譯成中文，這樣的文章對讀者、對社區又有什麼幫助呢？【我讀過這個框架的源碼】和【我修過這個框架的 bug】相比起來，哪一個的貢獻更大呢？

我的的觀點是，帶着問題去調試源碼，收穫會比簡單的閱讀理解大不少。在你真正須要解決一個 bug 的時候，你纔會真正去思考調用的順序、執行的流程、變量的意義，而後在一個個斷點、日誌和錯誤堆棧的幫助下，真正知道一些看起來漫不經心的判斷是多麼不可或缺，看似簡單的地方又隱藏着怎樣的預設條件。

從這個角度而言，以修復 bug 的動機驅動去維護開源項目，對技術水平的鍛鍊，會比在單純的源碼閱讀或在技術社區裏逛博客點贊要來的更高。而每個發展中的項目，都會有很多已發現或未發現的 bug 等待咱們去修復。在這個參與的過程當中，你的工做不只能讓社區收益，也可以更多地讓本身獲益。

不過，【如何閱讀源碼】已經脫離了本文的討論範圍。在此咱們點到爲止就足夠了。

友善的互吹評價

參與開源項目和搬運文檔相比，很重要的一點區別在於和其餘人之間的互動。你的 Issue 會有人評論、代碼會有人 Review，PR 也會有人點贊。這時候，和其餘人的互動是少不了的。在 Github 這樣的英文技術社區，合適的交流方式對促進社區發展是頗有幫助的。

這裏咱們只分享一點：如何更友善地對其餘人的工做做出評價。在中文社區，除了【伸手黨】之外，還常常可以看到【噴子】直接抨擊項目質量或者給人蓋上【抄襲】的帽子。不過，吐槽別人的代碼確定是少不了的。在社區中交流時怎麼樣更委婉地指出 PR 的問題或在 Issue 中回覆觀點呢？

頗有趣的一點是，在 Github 上不多看到這些詞：

bad wrong dirty terrible ***...複製代碼

更基本看不到這樣的說法：

I think this code is bad and do things wrong!複製代碼

與直接吐槽代碼 bad 相對地，不妨這麼說：

• 表達 API 笨重很差用，能夠說 heavy to work with
• 表達模塊結構很差，能夠說 not intuitive
• 表達處理方式太粗暴，能夠說 overkill
• 表達邏輯可能有漏洞，能夠說 leaky
• 表達要引入的東西太多，能夠說 aggressive
• ...

而 I think 則顯得很是武斷，能夠這樣：

• 萬能的 IMO 或 IMHO，即 In my (humble) opinion
• 補充一個 Not sure, maybe missing something
• 用 To my knowledge 或者 For me

以及，在請求其餘貢獻者 Review 或合併時，記得加上 Would you please 和 Could you please 也是很不錯的。哦對了別忘了 Thanks 啊。

總之探索合適的溝通詞彙是一件頗有趣的事情，不過對英語的要求並不高，運用上面的介紹其實只要初中英語水平就足夠了吧…相信有興趣的同窗可以總結出更多【開源黑話】😅另外，很多項目的 Code of Conduct 也值得一讀。

有效的溝通

貢獻社區的過程並非上來就把代碼砸到人臉上，許多 bugfix 都是須要和上游維護者討論方案後再作決定的。這時除了客氣的言辭外，溝通的方式也很重要。在此我的總結了這麼幾點：

提問式的反駁

蘇格拉底有種和人辯論的方式是，不停地向對方提問，直到對方答不上來爲止。在社區的交流中，這種方式一樣很常見。

好比，在認爲一個 PR 存在着未考慮到的邊界情形時，做爲 Reviewer，比起直接判斷 You are missing XXX，評論 How is it when XXX 就巧妙地【把鍋丟了回去】，可以客氣地讓提交者進一步說明對特殊狀況的判斷或修改代碼，而不是直接【把天聊死】。

一樣地，在不承認某種 Workaround 方式時，回覆 I don't know what you mean at... 而後等待對方的解釋，效果也比直接說 This is wrong 要更好。

注意描述方式

在提交 Issue 時，不一樣的描述方式可能會帶來不一樣的優先級與不一樣的處理結果。舉一個最近遇到的例子：

咱們參與的項目中，有一個描述【性能問題】的 Issue，內容大體是【輸入內容大的時候速度特別慢】。這個 Issue 被晾了一兩週沒有人處理。而我在調試後找到了一個特殊的場景，這時反覆的重繪會讓頁面崩潰。在將【頁面死循環】做爲標題提交 Issue 後，做者在當天就修復了這個問題，而性能問題也一併解決了。

模板與工具

其實上面的很多內容是有固定的套路可循的。好比，Issue 和 PR 都有相對固定的模板，幫助參與者提升溝通的效率。

對 Issue 來講，常見的模板大體是這樣的三段論：

1. Bug or Feature?
2. Current Behavior?
3. Expected Behavior?

而對於 PR 來講倒不必定須要長篇大論，正式一些的結構大體是：

1. This Closes #xxx
2. Current Behavior / Reason
3. Solution

在提交 Issue 時，提供復現的例子、步驟或 GIF 是很是重要的。這時咱們能夠用 JSFiddle 提供簡單的復現例子，在 Mac 上也有 Giphy Capture 這樣免費的 GIF 動畫錄製工具來提供幫助。

最後，在 Git 提交時，整潔的提交記錄也是很大的加分項，這方面有興趣的同窗不妨參考做者以前的文章：使用 git rebase 提升 PR 質量。

總結

參與到開源社區中是個既有挑戰也有成就感的事情。比起國內互聯網公司常見的招聘 slogan【你的一行代碼，能影響多少多少人】來，貢獻到開源項目中，就意味着【你的代碼可以被多少多少公司】使用，這無疑是更高的層次，也會有更多的挑戰。若是以爲平常的增查改刪邏輯已經讓你感到厭煩，那麼參與到社區中來或許能爲你打開新世界的大門。

這裏順便安利一下咱們目前維護的編輯器項目 Slate。這是一個優秀而迭代迅速的富文本框架，目前還處在大刀闊斧地添加新特性和新功能的 beta 時期，有很是多參與貢獻的機會，源碼的風格與註釋也至關完備。另外有趣的一點是做者和 Evan You 同樣有着設計師的背景（不妨想象一堆程序員給 UI 設計師寫的代碼修 bug 的場景）。我也在以前的博客裏安利過 Slate，但願能有更多的同窗來嚐鮮！

最後咱們引用 Chrome V8 項目的一個原則做爲本文的總結吧：

In short, do the right thing for the project, not the easiest thing to get code committed, and above all: use your best judgement.