開源總監寫的「苦澀指南」：真的，一般人別碰開源項目

編者按：開源很簡單，只要你想干就干對吧。也許，但如果你想在開源上取得成功，就得聽聽過來人的經驗教訓。做開源項目絕不僅僅只是寫代碼那麼簡單，甚至最困難的都不是寫代碼的部分，而在於你如何宣傳和推銷，如何做好維護，以及如何跟一幫噴子打交道。Formidable的開源總監用一篇苦澀的開源指南告訴你：如果你不是真心喜歡開源的話，最好不要去做開源項目了。

嗨，我是Ken。

我是Formidable的開源總監。

如果你聽說過我，可能是因為以下兩點中的一點或者全部：

我在Twitter上面是個話嘮

因為Slick Carousel、Webpack Dashboard、Spectacle、Cash……這些開源庫

今天我們主要關注第二點。最近（以及過去）有很多人問我開源方面的指導，今天是我覺得想寫一寫的日子。

不過在此之前，我會先談談為什麼你想做開源的問題，以及我的個人經歷。

為什麼你應該寫OSS（開源軟體）

說到為什麼，開源對你和你的職業生涯的好處可以列舉很多：

它可以為你的個人品牌創造奇蹟。如果你有一個很火的項目，大家就會熟悉你和你的工作

它可以為你的公司品牌創造奇蹟。提供和維護開源項目能提高品牌的知名度。讓員工有時間去做這個然後看看他們的想法變成現實，這可以讓人知道在這裡工作很棒

作為開發者你可以得到成長！你不再只是寫寫孤芳自賞的業餘項目腳本了。有人盯住你，所以你會有積極性去把東西做好。

你會得到回報。因為John-David Dalton寫了lodash而節省了你這個項目的開發時間一樣，你也許也會用你的代碼幫別人節省時間。你成為一個人人為我我為人人的社區的一部分。

感覺會很棒。雖然這個是個人體驗，但每次有人感謝你對其項目的貢獻或者告訴你有關你節省了他們時間的故事的時候那種感覺都非常奇妙。

這未必能幫你找到一份工作，因為大多數公司並不嚴格地根據GitHub的星星數量去招人，但是如果說這不會幫你得到一次面試機會我就是在撒謊。

我的OSS經歷

我還是承認吧。我是有史以來最糟糕的開源維護者。OK，也許不是最糟糕的，但我每次並沒有做到最好。

我曾經有過幾次未能正確地管理好開源項目，不過嘿如果不是因為我成功創建了數量可觀的項目的的話就沒那些事了。

但是，我從每一個項目的失敗那裡都學到了一些東西，並且利用從中得到的洞察來幫助我下一次做得更好，這些我後面會談。我當然越來越擅長這個了，但我希望一些讀者也能從我的錯誤中吸取教訓而不是再走彎路。

我決定簡要介紹一下我的經歷，因為相對於典型的OSS經歷我的有點不太符合常規。不管你信不信，我認為我的整個職業生涯大概給不到20個不是我自己的項目做出過貢獻。

我的第一個OSS項目大概是我最成功的項目。我記得那時候我還在一家廣告公司工作，在為紐約的一個大型時裝品牌創建電子商務網站。我是團隊的資深開發者，通常繁重的JS開發都是我乾的。跟我一起回到jQuery那時候的日子吧……

時尚電子商務比較有趣的一點是到處都是旋轉木馬。而且往往會有非常複雜非常有野心的設計。以至於現有的旋轉木馬/幻燈片庫都不夠靈活來支持他們提供給我的設計，所以我開始從頭寫旋轉木馬，用CoffeeScript來寫。這玩意兒行得通，但是當然並沒有讓我讓在同事當中更受歡迎。

所以我看到一個很明確的需求。得有一個足夠靈活的旋轉木馬插件來支持設計師扔給我們做的任何事情，而且還有易用易於修改。於是我就寫了。為我們大家。然後我覺得它很有用，既然如此為什麼不幫別人節省大量時間呢，於是我就把它開源了……

結果表明它的確幫別人省了大量時間，而且大家似乎都挺喜歡。在發布後的頭幾個月里，其熱度突破了天際。我對OSS還很陌生，對大家使用我的東西感到非常興奮，所以熱情高漲，甚至願意徹夜加班去修補問題，推出新版，確保沒人能與之競爭。

這些就不說這麼多了，因為這篇文章是想提供一些提示的，不是講我的故事：最後發生的事情是我停止了項目的維護。我宣布了幾件事。我換工作了，所以我再也不需要旋轉木馬了。我已經脫離了那個問題空間。React也出來了，我早早就開始研究，所以我對jQuery之類的東西再也沒興趣了。

但是最大的原因之一還是因為我筋疲力盡了。我做得太辛苦了。評論裡面個個都自以為是，說我們如何不應該使用旋轉木馬（即便我為了賺錢做得每一個項目都會有一個，而且都是手工設計），我變胖了，我妻子發火了。

從此之後，我在不同領域又做了幾個流行的庫，每一個都解決了一個不同的問題。我的最大恐懼之一是我再也不能寫出熱門的庫了，擔心點擊數不如人意。目前為止我仍能避免這件事情發生，雖然我還會時不時做一些蠢事出來，但是至今仍令我無法釋懷的還是對旋轉木馬項目的管理，那感覺就好像讓半個互聯網都失望了。

所以下面我要給大家介紹一些經驗，希望你能夠利用好它們做出成功的項目，而不是留下遺憾。

入門

開源跟演講很像。許多人並不認為自己推銷的東西足夠有價值。這純屬胡扯。如果你看過冒名頂替綜合征的東西的話，這完全是對的。每個人都有自己的獨特知識構成，沒有一個人什麼東西都懂完。你兜售的東西總會有人需要的。

我有兩個獨特優勢1）看得開 2）自信心爆棚，所以我只管寫出來，但是我注意到這兩點對很多人都比較困難。

我的建議：

儘管去做吧！

可能會發生的最糟糕的局面是什麼？別人會指手畫腳？我來告訴你吧孩子，哪怕你把最完美、最有用、最令人印象深刻的代碼放到GitHub上，你猜怎麼著？照樣有些混蛋會進來吐槽發牢騷。這是不可避免的。最糟糕的情況下你也能學到一些東西。有人可能會說，「嘿這搞得性能很糟糕」你要麼「呃我不會編程，算了我退出」，要麼「哦哇哦，多謝你的提示，剛剛改好，現在好點了。」要成為把它做得更好的那個人。

那麼你應該開發什麼呢？好吧，這個問題而可是價值百萬美元的啊。

我是這麼看的：

你有一個問題

對於這個問題你有一個解決方案

你提供的這個解決方案包裝得非常好，大家都想用你的解決方案去解決自己的問題

那麼我們就來談談如何包裝的問題……

API設計

假設你有了自己的想法。你有一個問題，現在你已經解決了這個問題。但是你還希望別人也用它對吧？以下就是一些提示告訴你如何讓別人也想用你的東西。

首先，要看看之前的技術和你的競爭對手。如果別人的庫做的東西跟你的一樣，你就得有與眾不同的東西才行。假設說你想開發下一個lodash。好吧助你好運。但除此以外，為了能爭取到lodash的市場份額，你得有吸引人之處。你的東西必須要有更小或者更快或者更好的API。知道為什麼我會這麼做了吧？

說到API設計，需要有一些平衡。你可以做一個開箱即用不用做任何事情的庫，可是這樣的話大家就會抱怨想要修改的東西。你可以做出最靈活、可配置型最強的庫，可這樣一來你就會成為Tobias Koppers/ Sean T. Larkin，而大家就會抱怨自己要做配置的工作。（對不起Sean，我是被迫的。V4版做的很不錯。）

你希望找到其中完美的平衡，既要儘可能方便使用，又能進行必要的配置。在此之上，你希望保持簡潔、明確以及可用。不要聰明過頭，否則的話你會惹毛所有人的。

我喜歡做的一件事是用非常明了但不聰明的方式寫源碼。因為這樣可以讓別人更容易做貢獻。東西是什麼就按照什麼命名，不要做自嗨式的編程，如果你要搞東西的話，要注釋一下為什麼。

這段時間以來我沒寫過一行代碼，直到我完成了一個心目中想要的模擬API。如果你要把它做成真正的API的話是要花些時間的，但這是一個值得努力的好目標。你會知道什麼時候API做對了的，因為那時候你會感覺喜歡上它。

準備好發布

現在你已經解決了你的問題，並且包裝得很好了。現在是是時候發布它了。但在你做之前，如果你希望別人使用的話還需要有些事情發生才行。

寫點該死的文檔。

這不是開玩笑。你的文檔得是有史以來寫出來的最好的文檔。避免用居高臨下的口吻去寫東西。你需要在開頭有類似標題鏈接索引這類的東西。你的有個開頭章節解釋那些如何讓這玩意兒第一次跑起來的折磨人的細節。你需要把API的所有邊邊角角以詳細到荒謬的地步全都寫出來。

如果你有一個方法，你應該把預期的參數、類型以及返回類型都寫進文檔裡面。你應該說明它做什麼。你應該給出例子來解釋如何去使用它。讓別人很容易就能使用你的庫。

你應該說明如何做貢獻。你應該說明如何運行所有這些編譯步驟。如果你引用了另一個項目，或者概念，要提供鏈接。如果你引用了任何可鏈接的東西，鏈接過去。

要徹底詳細，結果會大不一樣。

寫一些該死的測試。

給我仔細聽清楚。你應該把測試覆蓋到合理的佔比。原因是：

這會激發你對你的庫健康情況的信心

這會讓你充滿自信地合併PR（Pull Request）

這會讓你在暫停項目一段時間之後自信地繼續工作下去

有一次我發布了一個庫，但沒有經過測試，Paul Irish就說了，「如果做過一些測試的話就酷了。」自然，我的反應是，「哦天哪，是Paul啊」然後開始寫測試。寫了那些測試後我一共找到了15個BUG！謝謝你Paul！

如果你寫了任何東西，那就繼續寫點測試。求你了。這是錦上添花的事情。這可以省掉我很多時間和痛苦。

寫完測試後，把它在Travis或任何持續集成平台上設置好，你就能高枕無憂了。

使用類型

測試沒有抓到的bug，type都能抓到。現在如果你不對你的JS劃分類型，這種舉動就像開車不系安全帶一樣。此外，隨著越來越多的人使用TS（TypeScript）或者Flow，他們都假設type已經就位。用類型來寫庫，導出和提供類型，你會感謝我的。要麼讓別人到後面再給它標註類型，這將是第三方風格的，過時的可能還是錯誤的。你看著辦吧。

Repo（代碼倉庫）的先決條件

README.md

CONTRIBUTING.md

LICENSE.txt

一個有效的、填好的package.json

呃，README。你永遠應該把LICENSE.txt放進去，否則的話一些人就用不了你的代碼庫。授權用MIT就可以了。不要自作聰明自己寫一些授權聲明。只用MIT。寫吧。

CONTRIBUTING.md不僅是指出如何做這個項目的好地方，也是鏈接到/添加到你的行為準則的好地方。不管你同不同意這個概念，一定要增加行為準則，相信我。這會讓某些人對貢獻感到舒服並且參與進來，今後你要是有問題的話，這裡也是把討厭的人踢走時告訴對方原因的一個很好的指示牌。

錦上添花

假設你已經寫出了很棒的文檔。API設計的很好，所有的先決條件都就位了，並且你已經準備好讓你的代碼庫看起來比較像樣了。但我還有些意見。

勳章。沒有東西能像勳章那樣讓你的代碼庫看起來更加像樣了。勳章太多當然不好，但如果你納入一些有用的勳章的話，這就是正統的印記。這說明你很上心。

像npm版本，測試狀態，覆蓋率數據等這樣的東西也是很好的。

此外，Markdown支持裸HTML，所以你可以讓你的repo標題更好看點。把東西居中排列，添加引言，美化一下。

如果你真的想拿金牌的話，學著這裡（https://github.com/kentcdodds/all-contributors）一樣增加貢獻者條目。

認識給項目做貢獻的人真的是非常好。

發布 & 營銷

好了現在一切就緒了，是時候閃亮登場了。怎麼才能讓別人過來看看並且使用你的新庫呢？

我的建議非常具體。周一美東時間12凌晨發布。這是歐洲一天的結束，是紐約午休時間，而舊金山還在任何事情還沒做完的早上。這時候有大量的受眾正在滑動手指，在互聯網上閑逛呢。

至於怎麼發布，我想Twitter是第一站。做出大膽的聲明。

「厭倦了用鍵盤寫CSS？猜猜看，現在你可以用Xbox控制器來寫了！」

「Stack Traces讓你很沮喪？如果是在VR裡面跟蹤這些會怎麼樣？」

開干吧。但要有吸引力。使用圖片。或者視頻。要直截了當讓人明白它是做什麼的以及為什麼他們要使用它，附上鏈接。這個流程應該這樣：

你的代碼庫受歡迎程度可能要取決於粉絲數以及你向他們推銷的技術方向，但這些一般都是有用的招數。除了Twitter用戶以外，在HN（HackerNews）和Reddit上面發布也效果不錯。

此外，需要的話還可以跟著發布一起發表一篇博客文章，尤其是如果你是在公司的旗幟下做這件事的話。你可以用更長一點的形式展示出來。

要大膽。要有信心。準備好給你的東西留夠版面。

維護

我很害怕說到這一部分，因為這是通常是我經歷最糟糕的地方。不過我還是很樂意給你們談談我從各種失敗中吸取到的教訓，希望你們看了能夠知道會發生哪些事情。

現在你已經發布了你的庫。接下來可能會有兩種情況發生：

1、它失敗了。

誰會在意呢。我就經常發生這種事情。重頭再來過唄。有時候一些東西火不起來。這未必就意味著你很糟糕或者你的想法不行，只是時機不對罷了。重要的是你做出來了，你做對了。下一次你再開發的時候，你為成功所做的準備就更加充分了。給自己鼓鼓勁，下次加油吧！

2、它火了。

這時候才是你真正麻煩的時候。大家喜歡你的東西。他們在推特上面轉發你的東西。你得不斷改bug回答問題並且為你的想法辯護。對此我有一些看法。

首先，如果任何人對摺騰你的庫感興趣的話，讓對方成為維護者。再重複一遍：

如果任何人對摺騰你的庫感興趣的話，讓對方成為維護者。

原因是：時間會流逝，新的技術會出現，問題也會改變。你也會變。但你的repo還在那裡。如果你你委派別人的話，你就會碰上糟糕的時刻。你會因為維護而筋疲力盡，你會對這個項目心懷怨恨，這東西最後會變成你的負擔。相信我，這件事情授權給別人干。

接下來，我想談談跟人相處的事情。

這是開源最大部分之一，在很多時候甚至比寫代碼還要重要。等著吧，大家會吐槽你。他們各個都覺得自己有這個資格。他們會公開蔑視你的項目。

讓那幫傢伙見鬼去吧。

我已經花費了那麼時間在做東西上面，現在我希望能把精力放在別的地方。相信我，讓那些噴子見鬼去吧。

不過，要帶著警惕的眼光去辨別那些噴子。你知道，有時候有些人可能看起來像是個噴子，但其實不是。要考慮到這個，要知道你是把代碼發布給全世界。要記住並不是所有人都講你的母語。

想像一下你想給一個用俄語寫的repo做貢獻。但是你不懂俄語。於是你Google Translate「嘿這裡有個什麼時候實現這個的時間表）」。然後比方說Translate返回的俄語意思變成「這個什麼時候能完成。」乍一眼看過去你可能會覺得「嘿這個傢伙有什麼問題啊」，後來你才意識到在互聯網上意思的傳達做得不是那麼好，經過翻譯後就更加了。

要小心這個，有時候他們不是情緒失控，只是不講你的語言。

除此以外，我的最好建議是對你的PR（pull request）要有牢靠的CI（持續集成），要回答問題，要有PR模板。在代碼庫上你會遇到一堆的問題和PR，如果你想管理好這些的話，有一些基本規則是必要的。我的建議：

要求重現案例或者失敗的測試用例

要求提供bug發生的情況

某些一次性的bug意思哈沒有時間找出來的。讓用戶向你證明這個bug是存在的，並且讓你能夠方便地識別出來，這樣你就有時間去解決問題了。

此外，在CONTRIBUTING.md的某個地方指出大家應該在處理PR前在issue裡面跟你先討論一下想法是值得的。全世界最悲哀的事情莫過於有人非常努力地處理一個永遠也不會得到接受的PR。

說到接受PR，本節中我想告誡你的最後一件事是你不必去做別人要求你的東西。因為屈服於用戶我就浪費了很多力氣去做個API出來。

大多數時候，一些人要求一樣東西只是為了解決他們自己的一個孤立的問題，但是那個問題對於廣大的社區是沒有價值的。要警惕對你的API的任何修改，因為那些有著極端需求的人會把你的API搞砸的。要做對核心庫是對的東西，而不是幫一些搞滑翔機遙控系統的傢伙去解決問題。

哦我撒謊了，還有一件事。要恰當地使用語義版本控制。

求求你了。否則的話每個人都會失去理智的。還有推送標籤。還要寫版本說明。詳細的版本說明。隨著你的庫的不斷演進，讓投入到裡面的人知道發生了什麼是非常重要的。

要透明、清晰、有信息量。否決事情要有寬限期。如果別人投資了你的庫而你的修改讓他們的應用出問題的話，他們是不會高興的。用富有同情心的方式更新你的庫。

結論

到了現在，你大概已經意識到我不僅做OSS很糟糕，而且寫東西也是。但是有人要我寫，於是我就寫了。我希望這篇流水賬能夠幫助一些希望發布自己的開源項目的人，讓他們能節省一些時間，以及避免破壞到他們的心情。

這裡面有很多的坑，但是如果你每一樣都能照顧到的話，你的日子就會比我更加好過，成功的機會也會更大。

最後，我還有一個建議。除非你真的想做這個，否則的話不要做。不要覺得這是你必須做的。不做這個你也能找到工作。不做這個你也能成為一名好的開發者。我從中獲益良多，也非常享受做這個，但是我永遠也沒法把免費花在那些庫上面的時間給要回來了，我本來可以用來跟家人待在一起或者追求我的愛好或者做任何可以給我帶來收入的事情。做這個因為你想做。如果你對自己開發的東西沒有激情的話，你可能是不會成功的。

編譯組出品。編輯：郝鵬程。

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！