前言

各位好久不(bu)見，有些(xie)小伙伴(ban)可能知道大概1年多以前我開(kai)始維護項(xiang)(xiang)目（Java業務操(cao)作(zuo)日志記錄框架(jia)）。這期間(jian)項(xiang)(xiang)目陸(lu)陸(lu)續(xu)續(xu)更(geng)新迭代、發布新版(ban)本，一路走來也踩了(le)不(bu)少坑。這篇(pian)文章(zhang)主(zhu)要(yao)是(shi)想給(gei)希(xi)望開(kai)始寫開(kai)源(yuan)項(xiang)(xiang)目的(de)(de)同學們一些(xie)開(kai)源(yuan)項(xiang)(xiang)目維護的(de)(de)實操(cao)建(jian)議(yi)，也算(suan)是(shi)給(gei)自(zi)己(ji)梳理一下做一個開(kai)源(yuan)項(xiang)(xiang)目需(xu)要(yao)注(zhu)意的(de)(de)事項(xiang)(xiang)。

此外，本文(wen)討論的個人(ren)開(kai)源項(xiang)目(mu)僅限于(yu)代碼為主(zhu)的項(xiang)目(mu)。像一(yi)些新聞、教程(cheng)、電子書、工具集錦類開(kai)源倉庫，不在本文(wen)的討論范圍內。

當然了，如(ru)果你已經(jing)是一個經(jing)驗豐富的開(kai)源(yuan)項目maintainer，那么(me)請趕緊關掉(diao)這篇文章，并且聯系我，讓我好好抱(bao)大腿(tui) ：）

確定項目的主題和方向

首先(xian)，我們要(yao)重(zhong)點探討(tao)如何準備個(ge)人(ren)開(kai)源項目。一(yi)個(ge)最(zui)基礎的(de)思考是，你的(de)項目靈感(gan)從哪里(li)來？當你覺得有了好的(de)想法后，又應該做哪些事前(qian)調研工作？

積累靈感

積累(lei)靈感是開始一個開源(yuan)項(xiang)目(mu)的第一步。

很(hen)多時候靈感(gan)源自于我們(men)日常的(de)(de)學習和技術(shu)工作(zuo)上(shang)的(de)(de)積累。例如(ru)，在工作(zuo)中遇到的(de)(de)問題(ti)，想(xiang)解決的(de)(de)BUG，或者對某項(xiang)技術(shu)的(de)(de)深入研(yan)究(jiu)，它們(men)都可(ke)能給(gei)你靈感(gan)。

此外(wai)，每天多(duo)多(duo)閱讀技術(shu)文(wen)章、關注(zhu)技術(shu)新聞(wen)以及瀏覽Github Trending都是(shi)獲(huo)取靈(ling)感(gan)的好辦法，多(duo)元化地獲(huo)取信息對于積累靈(ling)感(gan)很重(zhong)要。

做好事前調研，非必要，不造新輪子

之(zhi)前碩士(shi)期(qi)間寫論文(wen)經(jing)驗的(de)(de)告訴我，當你(ni)對一(yi)個(ge)研(yan)究方(fang)向沒有了(le)解全(quan)面的(de)(de)時候，你(ni)的(de)(de)大(da)多數想(xiang)法是很幼(you)稚的(de)(de)，有很大(da)可能已經(jing)有前人替你(ni)踩過了(le)坑，或者有了(le)現成的(de)(de)框架(jia)和產品(pin)。

所以(yi)在確定(ding)你(ni)的(de)項(xiang)目(mu)主題(ti)之前，一定(ding)要(yao)充分的(de)進(jin)行(xing)調研(yan)和(he)搜索，保證你(ni)的(de)項(xiang)目(mu)在某個方面具(ju)有(you)獨特性。在調研(yan)過程中，你(ni)最好(hao)要(yao)羅列(lie)出現(xian)有(you)和(he)你(ni)相似(si)的(de)產品為何(he)不能滿足你(ni)的(de)訴求，而你(ni)的(de)項(xiang)目(mu)又和(he)他們有(you)哪些差異化的(de)特色(se)。

當(dang)然，凡事都不要走兩個(ge)極端，當(dang)你發現你的想(xiang)法真的非常獨(du)特，沒(mei)有(you)人(ren)做的時候，你要考(kao)慮下是(shi)(shi)(shi)否(fou)是(shi)(shi)(shi)因為成本(ben)過(guo)大，或(huo)者受眾過(guo)小的原因，才(cai)導致(zhi)沒(mei)有(you)現成的產品，那(nei)么你來做第(di)一個(ge)吃(chi)螃蟹的人(ren)，會(hui)面臨的工(gong)作量和難度，你自己是(shi)(shi)(shi)否(fou)心中有(you)數。

如果在(zai)經過認真的(de)(de)調研(yan)后，你發現(xian)你的(de)(de)想法確實在(zai)網絡(luo)上沒有(you)很好的(de)(de)產品，那(nei)么它可以(yi)作為(wei)一個好的(de)(de)發力點。

一步步維護好你的作品

OK，當你(ni)有(you)(you)了靈感，并且對(dui)于自己的(de)(de)這個(ge)想法(fa)十分有(you)(you)信心之后，讓我們來討論一(yi)(yi)下，當你(ni)準備(bei)正式開始一(yi)(yi)個(ge)項(xiang)目時，你(ni)應該遵循的(de)(de)一(yi)(yi)些方法(fa)和(he)我個(ge)人的(de)(de)經(jing)驗。

對(dui)于一(yi)(yi)個開(kai)(kai)源項(xiang)目，華麗的外表(biao)并非(fei)貶義。你(ni)(ni)可能需要(yao)花大(da)量的工作去做(zuo)編碼以外的工作。此外，你(ni)(ni)還需要(yao)一(yi)(yi)些(xie)推廣你(ni)(ni)開(kai)(kai)源項(xiang)目的手(shou)段，畢竟，如果一(yi)(yi)個項(xiang)目一(yi)(yi)直不(bu)被人看見，你(ni)(ni)也會很快失(shi)去動(dong)力。但是，不(bu)要(yao)害怕，有(you)一(yi)(yi)個好的、有(you)效的靈(ling)感其實已經成功了一(yi)(yi)半，讓我們從拙(zhuo)劣的模(mo)仿(fang)開(kai)(kai)始，慢慢成為大(da)師(shi)。

能者摹形，大師竊(qie)意。

先入為主，寫好README

很(hen)多時候我(wo)們點(dian)開開源項目(mu)主頁，首(shou)先就會大致瀏(liu)覽下項目(mu)的README，所以無論如何也(ye)要(yao)把第一印象(xiang)做好。

網上有很多(duo)關(guan)于如何寫開源項目(mu)README的文章，這(zhe)里(li)就不展開講(jiang)了，推薦一篇寫的還(huan)不錯的外網翻譯：

對于我來說，有個很喜歡(huan)做的事就是貼(tie)上很多小徽章，用(yong)戶會先入為(wei)主的覺得你的項目，有點“專業”。下面用(yong)幾個倉(cang)庫的截(jie)圖(tu)舉例子。

我的log-record也像上(shang)面的知(zhi)名(ming)倉庫一樣(yang)，依葫蘆畫瓢，貼上(shang)了(le)幾個我認為重要的徽(hui)章(Badge)

對于不(bu)同類(lei)型(xing)，不(bu)同語言的開源項目，README的寫(xie)法(fa)也千變(bian)萬化，我也沒法(fa)給大家推導出(chu)一(yi)個萬能公式，但是我可以給大家介紹幾類(lei)典型(xing)的README：

• : 經典Java框架，這種類似的開源項目由于其龐大的生態體系，其README主要是介紹其概念，隨后給用戶指引到各種外部文檔鏈接。同類型的還有：，等。
• : 框架類項目的中文README寫法完全可以參考它，Java用戶熟悉的跨線程ThreadLocal傳遞框架，同類型的還有：我自己的等
• : 工具類項目，用于監控各類服務狀態，其README基本就遵循了上文章提到的如何寫好工具項目README的方法，有LIVEDEMO，有徽章，有編譯、安裝方式，并且提供了詳細文檔的跳轉。
• ：還有一些帶學術性質的項目，比如很多大模型項目，其README會包含一些論文引用以及論文數據的復現方式等，同類型的還有：

請多多參考優(you)秀項目(mu)的README，將應有的模塊盡量補(bu)全，之(zhi)后慢(man)慢(man)迭代。

盡量清晰的項目結構

除了README，清晰(xi)的(de)目(mu)錄(lu)結構也(ye)很(hen)能(neng)吸引用戶(hu)(hu)，以hutool和我的(de)log-record為例，由于是Maven項目(mu)，可(ke)以盡量(liang)讓用戶(hu)(hu)能(neng)夠看出module區分。此外(wai)，會有一些額外(wai)的(de)文(wen)件夾，例如：

• .github: Github Action相關
• .gitee：Gitee Action相關
• docs: 文檔集合
• bin: 可執行腳本
• LICENSE：開源證書
• 等等。

比如hutool項目：

log-record項目(mu)則是按照Maven模塊進行了(le)簡單劃分：

良好的Git Commit

一個良好(hao)的commit記(ji)錄能(neng)夠讓使(shi)用(yong)者對項(xiang)目更(geng)有信心，也更(geng)有說服力，證(zheng)明其(qi)contributor都是(shi)（至少表面上是(shi)）對代(dai)碼(ma)質(zhi)量有追求的開(kai)發(fa)者。

我的Log-record，做的不(bu)好的是(shi)(shi)我中(zhong)英文混雜。如果你(ni)的倉庫明確面向中(zhong)文互(hu)聯網(wang)，你(ni)可以(yi)(yi)全部以(yi)(yi)中(zhong)文來寫，但是(shi)(shi)如果想面對全球用(yong)戶，還是(shi)(shi)盡量采用(yong)全英文為上策(ce)。

相反，一個差的(de)commit log讓人第一感(gan)覺就(jiu)是不專業。這一點要(yao)吐槽下hutool

做好版本管理

如果你做的(de)(de)是Java項(xiang)目，那么最(zui)(zui)好項(xiang)目能(neng)夠(gou)索(suo)引到公(gong)共Maven倉庫(ku)中(zhong)(zhong)，才能(neng)吸(xi)引更多用戶(hu)，畢竟用戶(hu)最(zui)(zui)需要的(de)(de)是方便(bian)地拉取你的(de)(de)包，而不是手(shou)動下載(zai)上傳到用戶(hu)的(de)(de)私有(you)倉庫(ku)里。其實大部分(fen)個(ge)人的(de)(de)Maven項(xiang)目都(dou)可以(yi)提交到公(gong)共Maven倉庫(ku)中(zhong)(zhong)，可以(yi)參考之前我的(de)(de)文(wen)章：

以我(wo)的(de)log-record項(xiang)目為例，我(wo)會按(an)照下(xia)面的(de)順序，進行(xing)版(ban)本迭(die)代：

• 開發新版本代碼
• 發行SNAPSHOT版，上傳至公共Maven倉庫
• 打Tag，發行RELEASE版，上傳至公共Maven倉庫

發行RELEASE版(ban)后(hou)，你的倉庫主頁上會有最(zui)新的版(ban)本(ben)信息，方便用戶查看和使用。

極為重要的測試工作

這一點希望大(da)家尤其重視，開源項(xiang)目(mu)，也要盡量對(dui)用戶負責(ze)，對(dui)項(xiang)目(mu)的(de)質(zhi)量有(you)追求，所以做好項(xiang)目(mu)的(de)單元測試(shi)(shi)和(he)其他集成測試(shi)(shi)等工(gong)作，并且最(zui)好能夠將(jiang)你(ni)的(de)測試(shi)(shi)覆(fu)蓋率展示出來(lai)，也能夠增強使用者(zhe)的(de)信心。

這(zhe)里推薦一(yi)個網站(zhan)codecov，它能夠通過(guo)多種方(fang)式幫(bang)你的倉庫維護一(yi)個測試覆(fu)蓋(gai)率(lv)數據，并且通過(guo)API讀取(qu)覆(fu)蓋(gai)率(lv)數據展(zhan)示在各種地方(fang)，比(bi)如(ru)展(zhan)示在README中(zhong)。

一份可信的更新日志

大(da)部分(fen)項目都(dou)需要有(you)明確(que)的Release Log/Update Log，用(yong)來向用(yong)戶展示(shi)倉庫(ku)的特性更(geng)新(xin)和問題修復，也能夠記錄一路以來項目的迭(die)代更(geng)新(xin)歷程。

恰巧(qiao)最近正在學習reactor，發現其(qi)子項目的(de)一個非常(chang)標準的(de)Release Log

善用其他包裝

在Github上，還有(you)一(yi)(yi)些(xie)包裝項目的好辦法，Github支持(chi)organizations，個人可以注冊(ce)一(yi)(yi)個虛(xu)擬的組織，用組織的名義建立(li)開源項目，往(wang)往(wang)更有(you)說(shuo)服力。

使用其免費版本(ben)即可(ke)，對于一個開源項目來(lai)說基本(ben)夠用。

Github的(de)更新還是比較(jiao)頻(pin)繁(fan)的(de)，及時跟上Github新的(de)功能(neng)和特性，也許會對你的(de)項目有更多(duo)的(de)幫助。

適當宣傳

當你(ni)的項(xiang)目有了(le)一(yi)個(ge)最基礎的雛(chu)形(xing)時，你(ni)可以慢慢開始你(ni)的宣傳工作。還是(shi)那句話，不要(yao)覺得宣傳有什(shen)么可恥的，如果一(yi)個(ge)項(xiang)目一(yi)直不被(bei)人看見，你(ni)也會很快失去動力。那么你(ni)會更容易半途而(er)廢。

對于個人小項目(mu)，有一些常規的推廣方式：

• 技術公眾號推廣：比如向一些有流量的大公眾號主做推薦，投放。
• 參與技術社區推廣：發布文章&參與活動
• Github和Gitee活動推廣

開源是個苦力活

最后一個(ge)(ge)章節(jie)，我們聊聊，做一個(ge)(ge)開源項目，我們到底為了(le)什(shen)么(me)？出名？純粹好玩？實現個(ge)(ge)人價值？體(ti)現開源精神？賺錢？還(huan)是(shi)...老實說，開源真的是(shi)個(ge)(ge)苦力活。

不要期待經濟回報，請用愛發電

如果你的(de)(de)開源項目(mu)已(yi)經(jing)在(zai)穩定(ding)維護(hu)，并且有一(yi)定(ding)的(de)(de)用戶(hu)正在(zai)使用，那(nei)么恭喜(xi)你，項目(mu)走上了正軌(gui)。但是(shi)需(xu)要潑冷水(shui)的(de)(de)是(shi)，大部分(fen)就算是(shi)有名的(de)(de)開源項目(mu)，很(hen)多時候(hou)是(shi)沒法給你帶來等價(jia)的(de)(de)商業回報的(de)(de)，你很(hen)可(ke)能在(zai)很(hen)長一(yi)段時間(jian)里都在(zai)用愛發電。

它能(neng)(neng)給你的主要是(shi)成就(jiu)感和一點(dian)小(xiao)小(xiao)的知(zhi)名度(du)，以及這些(xie)(xie)知(zhi)名度(du)背(bei)后(hou)可能(neng)(neng)帶來的一些(xie)(xie)附加價(jia)值（這就(jiu)很難去描述(shu)了(le)）。

如果你真的想要通過它得到(dao)一些金(jin)錢(qian)回(hui)報，那在(zai)你的項(xiang)目小有名氣后，以下(xia)幾種(zhong)方式可能會有效果：

• 提供有償技術支持。
• 打造商業版本，區別于社區開源版，商業版閉源并向用戶收費。
• 尋找一些推廣商，在你的項目代碼倉庫和文檔中植入其“廣告”。
• 其他野路子...

這些事情(qing)的背后都要大(da)量的時間(jian)(jian)和(he)精力去推(tui)動，如果你和(he)我一(yi)樣是一(yi)個上班族，那么大(da)概率你沒法同時兼顧工作和(he)維護(hu)一(yi)個持(chi)續保持(chi)活(huo)躍的大(da)型項(xiang)(xiang)目。所(suo)以(yi)很(hen)大(da)可能是，你的項(xiang)(xiang)目在很(hen)長時間(jian)(jian)內(nei)一(yi)直(zhi)是一(yi)個小而(er)美的項(xiang)(xiang)目。

伸手黨

當你的(de)項目有了(le)(le)流量，被很多(duo)開發(fa)同(tong)學(xue)搜索到了(le)(le)，你會獲得很多(duo)流量附帶(dai)的(de)東西。

伸手黨就是其中一個，具(ju)體來說(shuo)就是有很多網友，會要求你添加很多他(ta)們(men)(men)能(neng)想到的(de)功能(neng)或者(zhe)他(ta)們(men)(men)覺得你項目應(ying)該(gai)提(ti)供的(de)功能(neng)。

遇到這(zhe)種情況(kuang)，你需要用(yong)(yong)心判(pan)斷，他們所要求你添(tian)加的功能是(shi)否背離你本身項目(mu)的初衷，如果是(shi)，那么請忽(hu)視這(zhe)些建(jian)議(yi)。如果是(shi)合理的功能，那么請考慮加入，但是(shi)可(ke)以和用(yong)(yong)戶(hu)說(shuo)明，會(hui)在下(xia)一個里程碑中(zhong)加入，不要讓用(yong)(yong)戶(hu)過于期待你能很(hen)快完成。（如果用(yong)(yong)戶(hu)真的很(hen)希望(wang)能立馬用(yong)(yong)到此功能，你可(ke)以建(jian)議(yi)他自己開(kai)分支提交PR）。

無窮無盡的ISSUE

除了伸手黨之外，還會有(you)(you)很(hen)(hen)多用(yong)戶(hu)在(zai)ISSUE區問很(hen)(hen)多問題，例(li)如(ru)我的(de)log-record倉庫下(xia)這(zhe)些例(li)子(zi)。很(hen)(hen)多時候(hou)，用(yong)戶(hu)對你的(de)項目不熟悉，自(zi)然會有(you)(you)一些提問，當遇到重(zhong)復(fu)(fu)的(de)提問時，要有(you)(you)耐心，你可以盡量(liang)關(guan)聯到重(zhong)復(fu)(fu)問題的(de)老ISSUE上，讓他(ta)們自(zi)己跳過去看(kan)。

此外，善用Github提供的各種(zhong)標簽，歸類功能，把ISSUE分類，也(ye)是間(jian)接給用戶參與感，讓他們知道你正在跟(gen)進處(chu)理(li)這(zhe)些問題。

左右為難的PR

ISSUE雖然比較多并且你(ni)很可(ke)能覺得有(you)些毫無意義，但是畢竟他(ta)們只是用戶的提問(wen)或者給(gei)出建(jian)議，我們可(ke)以選(xuan)擇(ze)是否(fou)接(jie)受。

但(dan)是(shi)(shi)PR其(qi)實(shi)是(shi)(shi)比較尷尬的(de)(de)問題，很(hen)(hen)多用戶的(de)(de)PR很(hen)(hen)可(ke)能是(shi)(shi)對你(ni)的(de)(de)代(dai)碼進(jin)行了(le)很(hen)(hen)大的(de)(de)改(gai)(gai)動，有(you)時候這(zhe)些改(gai)(gai)動你(ni)其(qi)實(shi)并不愿(yuan)意接(jie)受。但(dan)是(shi)(shi)有(you)的(de)(de)PR，用戶花了(le)精(jing)力和心思對你(ni)的(de)(de)代(dai)碼進(jin)行了(le)大面積(ji)的(de)(de)改(gai)(gai)造（至少在他們心里，這(zhe)些改(gai)(gai)造是(shi)(shi)非常好的(de)(de)）。

這種情(qing)況(kuang)下，大家都會(hui)感覺到進(jin)退兩(liang)難，如果(guo)接受PR，可能(neng)代碼(ma)有(you)些地方就和你預想的越(yue)(yue)來(lai)越(yue)(yue)偏(pian)，如果(guo)不(bu)接受，就顯得不(bu)近人情(qing)。這種情(qing)況(kuang)，我也沒有(you)想好(hao)非常(chang)好(hao)的對(dui)策(ce)，目前我的策(ce)略(lve)，是嘗試做一(yi)個(ge)冷血無情(qing)的。如果(guo)與(yu)這個(ge)提PR的用戶還有(you)很(hen)多交流，那就盡量(liang)用你對(dui)項(xiang)目的看法和他(ta)進(jin)行交流，讓他(ta)按(an)照你的要求更改，或(huo)者是讓她(ta)自己fork你的項(xiang)目，自成一(yi)派(pai)。

像一些(xie)大型的項目，它們也有很(hen)多PR沒有被接(jie)受(shou)，且長時間擱置在那邊(bian)，例如(ru)SpringBoot