史上更全的開源項目創做指南

前言

開源，是這個時代的主旋律。做爲一名Android開發工程師，我有理由相信咱們是開源的最大受益者，由於那個養活咱們的Android其自己就是Google的開源項目。在這樣一個開源的時代，就連以前那個最排斥開源的"微軟"也不得不積極擁抱開源，大手筆收購github以表本身的開源決心。

前段時間我在逛github的時候，偶然間發現，個人github已經擁有12個star過百的開源項目，2個star過千的項目。回首一想，原來我作開源項目已經快3年了，想一想這一路走下來真的很是不易。

深夜和週末是我作開源項目的主戰場，電腦和AndroidStudio是我創做的紙筆，各類bug和issues是我通往卓越項目的攔路虎，常常爲了解決一個問題獨自思考到凌晨。這其中還要飽受噴子們的挖苦和質疑，以及白嫖黨的奪命連環call。固然，也會有人站出來講幾句公道話，可是平心而論，國內的開源環境真的不好。

若是不是由於對技術的熱愛以及支持者的鼓勵，我相信我很難堅持下去，就像那些漸漸消失的開源項目創做者同樣，提交記錄永遠地停留在了那一刻。

因此，爲了可以記錄下個人這段艱苦開源之旅，同時也是但願可以改善國內的開源環境，幫助更多但願從事開源項目的有志青年，我決定寫下這篇開源項目經驗總結。

爲何作開源項目

在決定作開源項目以前，你很是有必要問一下本身：我到底爲何要作開源項目？不管是出於什麼目的，只要你有答案的話，那麼你就能夠繼續往下看，不然如下的內容可能對你來講沒有任何意義。

提及開源，就不得不提Google這家極具開源精神的公司。做爲一家美國科技公司，每一年都在不斷地對外輸出着無數優質的開源項目，與此同時，近幾年咱們國家的科技公司們也開始着手開源計劃，開源了很多有趣的項目。

那麼爲何大型的科技公司都在積極地作開源項目呢？其實緣由很簡單，無非就是爲了名氣和企業的形象嘛。做爲一家市值超百億的科技公司，不搞點開源項目出來裝裝逼，都很差意思說本身是大廠。

那麼做爲咱們我的開發者而言，有必要作開源項目嗎？在回答這個問題前，你有必要問一下本身：你真的熱愛作技術嗎？若是說你作技術的目的只是爲了養家餬口的話，我以爲接接私活，作作外包比較適合你。由於作開源項目真的是那些"閒得蛋疼"的人打發時間的玩具，在這條道路上你會發現很是沒有"錢途"。只有當你真正將技術做爲一種興趣來熱愛的時候，你才能體會到那種開源項目被無數人引用後的價值和喜悅感。

因此，說了這麼多，咱們究竟爲何要作開源項目呢？如下列舉個人幾點理由，供你們參考：

• 提升本身的技術水平。畢竟開源項目就至關於把本身扒光了給別人看，也許這樣比喻不是很恰當，但確實能提升本身代碼的質量和解決問題的能力。畢竟若是你的開源項目真的有人用的話，你必然會收到不少的issue以及建議，這些東西可能你以前根本就沒有想到。
• 讓項目變得更加健壯。開源的最大妙處就在於，任何人都有權利看到你項目的代碼，提出本身的建議。這其中就有可能發現項目中存在的漏洞，以及一些很是有建設性的建議，同時也能讓你明白本身項目中存在的不足，這樣就會推進項目不斷的優化升級，項目的質量也會呈螺旋型上升而變得更加健壯。
• 結交志同道合的朋友。你在作開源項目的同時，很容易就能結交到與本身志同道合的開源創做者，畢竟你們都是但願開源項目越作越好，頗有可能你的開源項目被其餘的開源者所賞識而一同開發和維護。這樣一來一去大家頗有可能成爲"同志"，哈哈。
• 幫助他人，提高本身的行業影響力。這也是不少人作開源的重要目的。若是你有幸可以在某個領域作出一個很是優質的開源項目而且有不少人引用的話，那麼你在該領域的名氣必定會蹭蹭的往上冒，到那時什麼都會有的，具體可參考vue.js的創做者：尤雨溪。
• 展現我的的技術水平。不少人作開源項的目的就是它可以在應聘面試中加分，尤爲是應聘某些大廠。由於經過那短短几小時的面試其實並不能很全面地考察出一我的的技術水平，並且面試一般僅僅是兩我的面對面空談幾小時，若是這個時候你能拿出一個較爲優秀的開源項目的話，必定會加分很多，至少能在面試前給面試官營造一個不錯的印象。
• 實現本身的人生價值。開源給予了你無窮大的創做自由，在上面沒有產品經理提出的各類腦殘需求，也沒有測試提出的各類過分測試bug，更沒有各類技術條條框框以及企業規範。你能夠作任何你認爲對或者感興趣的事情；你能夠實現本身兒時改變世界的夢想；你能夠留下你在這個世上存在過的印記；你能夠...開源給予你無窮大的舞臺，你能夠作不少有意義的事情，當熱前提仍是不能違法法律...觸犯法律的事情咱們不能作，畢竟仍是保命要緊，哈哈。
• 收穫意想不到的業餘收入。雖然開源是免費的，不該以盈利爲目的。可是不得不說沒有經濟效益的驅使，單純靠對技術的熱愛實際上是很難堅持下去的，尤爲是當你面對不少現實生活的壓力時，情懷就顯得那麼蒼白無力，這也是爲何各大開源平臺都爲開源者提供了贊助和打賞的渠道，畢竟開源者也要賺錢生活。好的開源項目實際上是可以收穫至關可觀的打賞的，更有甚者能夠搞一個商用版，受權使用，賺取服務費等，固然能作到這一步的開源項目仍是很少的。

如何作好開源項目

上面我簡單講述了咱們爲何要作開源項目，若是此刻你心中有了答案，那麼恭喜你，你已經成爲一名準開源創做者，那麼下一步咱們就是探討如何作好一個開源項目。

我作了近3年的開源項目，其中最爲成功的 XUI 近600次的代碼提交，齊全的文檔和視頻教程，目前也不過收穫了2.7k的star量，因此說作好一個開源項目實際上是很是不易的。

下面我就簡單拿 XUI 項目爲例，簡單介紹一下衡量一個開源項目質量的幾項指標。

• 項目的熱門程度：項目的star、fork和watch量。
• 項目的活躍度：這裏考量的因素包含issue的整體數量、open issue和closed issue的數量、issue回覆和解決的速度、pull requests的數量、項目最後一次提交的時間。
• 文檔是否齊全：是否有wiki或者README.md。
• 項目的穩定性：代碼提交的頻率，項目版本發佈的頻率。
• 項目的潛力：項目開發的分支數、項目的開發計劃以及項目參與者的數量等。
• 項目代碼的質量：設計是否合理，是否符合設計模式原則，考慮項目的可擴展性、便利性和穩定性。
• 開源做者的水平：做者其餘項目的star量和行業影響力。

只有瞭解了以上指標，咱們才能創做出更加優質的開源項目。那麼說了這麼多，咱們如何才能作好一個開源項目呢？請繼續往下看！

1.選對開源託管平臺

開源託管平臺以 github 做爲首選，碼雲 做爲備份。

雖然目前市面上開源項目的託管平臺很是多，好比：碼雲、碼市、gitlab、BitBucket、SourceForge，不過我仍是極力推薦github，畢竟github使用的人羣最廣，人數最多，誰不想本身幸苦創做的開源項目能被更多人看見呢。雖然github是一家美國企業，往後有被禁掉的風險，可是我相信一個崇尚自由、民主的國家，對禁開源平臺這件事情仍是不會那麼順利的，畢竟開源無國界，開源不該政治化，商業化！若是你仍是擔憂github往後會被禁，那麼很簡單，你直接把你的github項目一鍵導入到碼雲中做爲備份，畢竟碼雲是獲得國家承認的，仍是比較可靠的。

2.好的創意或者理念

若是一項功能、一件事情你們每次都須要重複去作，可是又沒有什麼好的解決方案或者輪子的話，這個時候咱們就能夠嘗試去作一個。

一個好的開源項目都是爲了解一個問題而誕生的。若是你有好的創意或者理念，那麼你就更能吸引更多的人蔘與到項目的建設中，那樣也會有更多的人關注到你的項目，這樣你的項目想不火起來都難。

我當初創做 XUI 就是但願可以簡化Android界面開發的難度，提高Android界面開發的效率而作的嘗試。相信作過Android的人都知道Android原生組件在國內很不受設計師的待見，至於Google推行的Material Design設計風格更是無人問津，這就致使了設計師給出的原型圖幾乎是清一色的IOS風格，更尷尬的是，網上Android相關的開源UI庫是少之又少，幾乎全部的基礎組件都須要本身重寫。正巧當時我接觸到了React和Vue，發現它們都有很是方便的UI庫，直接在示例代碼的基礎上修修改改就能大體上實現本身想要的效果，極大地提升了開發的效率,後來我又借鑑了QMUI 相關的思想，最終創做出了 XUI 這個開源項目。

因此，一個好的創意或者理念對於開源項目來講很是重要，能夠說是開源項目的靈魂。

3.好的設計和代碼質量

若是說一個好的創意或者理念是開源項目的靈魂的話，那麼一個好的設計和代碼質量就是開源項目的骨骼和肉體了。

3.1 掌握設計模式

要想有好的設計，首先你須要很是熟練地掌握設計模式，那麼如何才能熟練地掌握設計模式呢？在這裏我能夠教你們一些經驗：

• 1.首先了解設計模式的幾大基本原則。這裏我有一篇講關於 設計模式原則的博客 可供你們參考。
• 2.其次初步學習現有的二十幾種設計模式，並在平時的工做或者開源項目中嘗試使用。這裏我有一個專門介紹設計模式使用的開源項目 ,裏面有相應的介紹和源碼可供你們參考。
• 3.最後等你熟練使用了上面的二十幾種設計模式後，忘掉他們，從新回顧以前的設計模式基本原則，並以此做爲往後項目設計的基本原則。

其實學習設計模式很是像武俠小說中修練一門武功，學習設計原則是修煉心法、內功，而學習現成設計模式則是修煉招式。只有提高內功，牢記心法，忘記招式才能真正意義上掌握了設計模式這一項技藝。

3.2 嚴格的代碼規範

提升代碼質量最簡單的途徑就是嚴格遵循通用的代碼規範，這裏我推薦阿里巴巴Java開發手冊 和它的IDE插件p3c項目 。

只有遵循通用的代碼規範，這樣才更加利於開源項目的多人協做，除非你想一我的維護整個項目，不然你的代碼寫得那麼騷，誰能看得懂？

4.豐富的案例或者測試用例

做爲一個合格的開源項目，提供一些單元測試用例仍是很是有必要的，由於你寫出來的東西並無專門的人給你測試，這個時候若是尚未相應的單元測試用例，你如何保證你寫出來的東西不是個坑呢？

若是你的項目不太適合寫單元測試用例的話，那麼你最好能提供豐富的使用案例，這樣才能讓你的開源項目更具吸引力，讓別人有東西能夠上手實踐，不然光禿禿的啥也沒有，你寫這個項目的意義又在哪裏？

5.完善的文檔

這裏的文檔主要包括README（簡介）和wiki（使用文檔）。下面是文檔的幾項基本要求：

• 1.文檔內容應當儘量的簡潔明瞭，井井有條，而且將其放置於顯眼的位置，便於他人尋找。
• 2.文檔應當及時更新，避免出現文檔與代碼不一致的狀況。
• 3.提供多語言版本的文檔，至少英文版文檔是要有的。

5.1 README編寫

README可謂是開源項目的門戶，每一個人都是從閱讀你寫的README開始瞭解你的開源項目的。README寫得好與壞，可能直接關係到別人在你的開源項目主頁上停留的時間，以及他們是否會給你的項目一個小星星，記住這裏很關鍵！

若是你以前歷來都沒有寫過README，那麼這裏我推薦一個國外人寫的教科書式的項目Standard Readme ,裏面寫的內容很是經典，能夠拿來借鑑。

那麼，一個寫得好的README應當包含哪些內容呢？如下是我總結出來的經驗僅供參考：

• 項目簡介（必須）：用幾句話簡要描述你的項目特色、優點以及項目目標（解決何種問題）。
• 做者簡介（選填）：這裏是你推廣本身或者其餘項目的地方。
• 項目背景（選填）：這裏能夠寫你創做該項目的原因和過程。
• 項目特色（必須）：這裏是你區別於其餘項目的關鍵，能夠寫你項目獨有的功能、優點、理念等。
• 項目設計（選填）：這裏能夠闡述項目的設計思想和理念。你能夠藉助流程圖、思惟導圖、UML類圖、時序圖等方式進行闡述。

• 項目演示（必填）：這裏是別人能最直觀感覺項目魅力的地方。你能夠經過如下5種途徑進行演示。

  • gif動畫演示
  • 視頻演示
  • 圖片演示
  • 在線演示
  • Demo下載
• 集成/安裝指南（必填）：這裏你得告訴別人如何才能快速地使用上你的項目。
• 使用文檔（必填）：這裏你須要告訴別人該如何正確使用你的項目，越詳細越好。固然若是內容過多的話，仍是建議直接給一個使用文檔首頁的連接或者視頻教程，這樣可能會更友好一點。
• 相關項目（選填）：這裏是你推廣其餘開源項目的地方，是讓你的項目粉絲數產生裂變的地方，必定不要錯過。
• 如何貢獻（選填）：這裏的貢獻包括兩個方面：代碼貢獻和打賞和贊助。對於代碼貢獻，你須要寫出你的提交規範和行爲準則，以免沒必要要的麻煩。
• 特別感謝（選填）：這裏寫上對你項目有過幫助或者啓發的人或者項目的地址，以此表達對他們的感謝。
• 聯繫方式（選填）：這裏能夠寫你爲此項目建立的QQ技術交流羣、微信公衆號等。
• 許可聲明（選填）：這裏你能夠寫你項目的開源協議或者許可以使用的範圍（好比：禁止用於商業用途，僅供學習）。若是你分免費版或者商用版的話，也能夠在這裏進行說明。

具體內容你能夠參考 XUI項目的README 或者個人README模版 。

5.2 wiki編寫

wiki的編寫和及時更新很是重要。wiki最好分模塊進行編寫，作到條理清晰，井井有條，通俗易懂。

下面我就以個人另外一個開源項目XUpdate 的wiki來簡單說一下，wiki咱們該如何編寫。若是你會在線文檔編寫的話，這裏能夠直接跳過。

wiki主要能夠分爲三塊，如上圖所示，最上面是項目的簡要描述，左側是文檔的首頁，右側是文檔的目錄。這裏我爲了偷懶，左側的文檔首頁直接照抄了右側的文檔目錄。

下面我簡單列舉咱們的wiki中應當包含哪些內容：

• 簡介：雖然這裏的簡介絕大多數是和README重複的，可是最好仍是不能漏。

  • 項目簡介：這裏包括項目描述、項目特色、項目背景、項目設計思想等內容。
  • 集成/安裝指南：若是你的項目是輪子庫，那麼就編寫集成指南。若是你的項目是完整項目，那麼就編寫安裝指南。
  • 項目演示：gif動畫、視頻、圖片演示，在線演示和demo下載二維碼任選幾項提供便可。

• 若是使用

  • 基礎使用：顧名思義，可以知足最基礎需求的使用介紹。
  • 進階使用：這裏主要介紹一些個性化（自定義）、深刻使用的操做。
  • 常見問題：常見問題的整理很是重要，它每每產生於issue或者技術交流羣中常見的問題，對剛接觸該項目的人很是有用。
• 配套設施：一個優秀的開源項目每每會自建相應的生態，這時配套設施就很是有必要了。

6.合理的版本管理和規劃

新版本的發行不宜過於頻繁，也不宜間隔時間過長，胡亂無規律的版本發行對使用者而言簡直是場災難。

最恰當的作法應該是：在保證充分測試沒有問題以後，按期發佈最新版本，實時更新項目的最新進度以及將來的開發計劃。

這裏我提供幾點建議供你們參考：

• 每次在進行新版本的開發時，建議單獨拉一個dev版本分支，減小對主分支的影響。

• 可使用github上的projects來規劃你的項目開發計劃。

• 能夠在issues中建一個置頂的issue來收集使用者的反饋，以此做爲新版本開發的規劃素材。

• 每次新版本發佈的時候，必定要提供詳細的版本日誌，方便使用者參考和追蹤。同時，對於幾個改動比較大的版本調整必定要有明確的說明，不然使用者會很是疑惑。

7.關注反饋，持續更新

7.1 及時處理issue

issues是使用者與項目開發者之間溝通的橋樑。不少使用者提出的issue仍是很是有建設意義的，及時高效地處理掉它們，可讓咱們的項目變得更加完美。

在處理issues的過程當中，咱們能夠收集整理"常見問題"，收穫好的idea，瞭解本身項目存在的不足等。這就要求咱們須要及時關注和處理使用者提出的這些issues。

那麼咱們怎樣才能快速高效地處理issues呢？這裏我提供幾點建議：

• 1.提供issue模版，過濾無效issue，提高溝通的效率。這裏你能夠參考 XUI的issue模版 。

• 2.自定義issue標籤，對issue作分類管理，部分issue能夠優先處理。

7.2 歡迎PR，及時處理PR

在開源項目初期，靠一我的維護一個項目仍是不難的。一旦項目熱度上去來，光靠一我的的精力是遠遠不足以維護整個項目的，這裏我深有體會。

因此咱們須要提供PR提交規範和行爲準則，積極歡迎更多的人蔘與到項目的維護中。同時對於別人提出的PR，咱們要及時review驗證，對於沒有問題的提交應當適時合入以提升別人參與貢獻的積極性。

8.作好推廣

酒香不怕巷子深，這句名言在互聯網時代是行不通的。你就是有再好的創意、再好的設計，若是沒作好推廣的話，也是沒人能看到你的開源項目的。

如何推廣本身的開源項目，對此我仍是很是有經驗的，下面我就提供幾個途徑：

• 在各大技術論壇、博客、社區不斷地發文章介紹本身的開源項目。我經常使用的幾個平臺有：CSDN 、掘金 、思否 、簡書 、知乎 、嗶哩嗶哩 。
• 在一些開源項目推薦分享平臺上提交本身的項目請求收錄。好比個人開源項目XUI 和 XUpdate 提交到了HelloGitHub 上。
• 組建本身的開源社區。你能夠建立qq交流羣、微信公衆號或者社區網址來推廣你的項目。
• 加入知名的組織。好比我就加入了B3log 開源社區 。

9.不忘初心，擺正心態

作開源項目是一件很是漫長的過程，你可能根本想象不到前方的道路有多麼的曲折。

假如你的開源項目作了幾個月了也無人問津，不要氣餒，專心去作你認爲有價值的事情便可，總有一天會有人發現你項目的價值。

假如你的開源項目作成功了，在收穫到很多人讚揚的同時，那麼勢必會遭到不少噴子們的冷嘲熱諷以及各類無腦噴。不要理會那些只會噴可是啥也不會作的麻瓜，不要把你有限的精力放在這些人身上。請把你有限的精力放在那些給你開源項目提出寶貴建議的人身上，專心去作你認爲對的事情。

最後

我花了整整一週的時間整理才寫下了這篇文章，也是真誠地但願可以改善國內的開源環境，幫助更多但願從事開源項目的有志青年。若是你以爲有用的話，建議你收藏此文章。最後，仍是祝願你們能早日寫出屬於本身的優秀的開源項目！！！

微信公衆號

更多資訊內容，歡迎掃描關注個人我的微信公衆號:【個人Android開源之旅】