查看: 5458|回復: 0

[JavaScript/JQuery] 從零做一個前端開源項目

發表于 2018-5-12 08:00:02
前言

每個程序員都應該有自己的 github 賬號,并貢獻自己的代碼

本文將像您介紹,如何從零做一個前端的開源項目。如果您對 github 和開源不熟悉,又想開始自己的開源項目,可以通過閱讀本文來入門。

另外,本文將會錄制成免費的視頻教程,文中如果有寫的不詳細的,視頻中肯定會詳細講解。待錄制完之后,我會把鏈接貼在這里


目錄

由于本文內容較多,先列一下目錄供參考。

什么是開源? 為何做開源? 做什么? 注冊賬號 搭建開發環境 提交代碼 創建官網 如何宣傳? 持續迭代 總結
什么是開源?

您可能有很多次打開 github 去查閱下載一些項目的源碼,但是您有沒有總結過,開源項目到底是什么?

我與開源

我是開源編輯器 wangEditor 的作者(歡迎去 star),這個項目已經做了有近 4 年了,目前積累了 4.5k star(現在是 2018.5)。4 年時間,我一直未間斷維護升級,其中還經歷了 2 次大型的重構,積累了一些經驗和教訓。接下來我將根據自己的經歷,來為大家分析開源。

開源項目包含什么

開源軟件并不是只是一堆源代碼,如果你仔細分析或者有親身體會的話,包含內容還是比較多的。我總結了以下內容:

源碼 文檔,如二次開發文檔和用戶使用文檔 開發環境,告訴二次開發者如何搭建和運行代碼 允許他人貢獻代碼,而不是僅僅給別人閱讀源碼的權限 問題,用戶提問,維護者答復,問題共享(而不是私聊) 問題列表和升級計劃,記錄當前問題,以及何時解決、何時升級 其他配套設施

要做成一個成熟靠譜的開源軟件產品,除了以上源碼相關的方面,還需要以下配套的設施,才能完備。

官網,如 wangEditor 官網 文檔,可以和官網整合在一起 問答社區,wangEditor 的問題社區就用了 github issue 及時交流社區,即 QQ 群、微信群
為何做開源?

做開源不掙錢,這是確定的,但是為何要做開源,而且那么多人堅持做開源呢 —— 他們不是完全為了興趣愛好,完全下班沒事兒干。人只要付出勞動、付出努力,都是奔著目的性去的,有興趣的原因,但是能讓自己持之以恒做下去的,肯定不是興趣。

其實這個問題很簡單,就像看書不掙錢(買書還花錢呢),但是為何要看書呢?因為大家都知道看書能提高自己的知識面和能力。而做開源也有相似的想過,只不過很多人沒接觸過不知道而已。我總結了如下幾個理由:

全面提高編程能力。 你需要從 0 打造,每部分代碼都需要自己負責,不像在公司中的一顆螺絲釘。 提高自己的社區知名度。 github 上的 star 能間接的反應你的身價,它能讓你得到業內認可。業內同行認可了,做啥事兒都好做,如內推工作。 鍛煉自己的產品意識。 因為做開源做的是產品,不再是單純的技術活,UI、運維、推廣、收集反饋、甚至成本預算,你都得考慮。 技術范兒、極客精神。 作為一名程序猿,能業余打造一款開源產品是一件很帥的事情,滿足自己的虛榮心。

有了充分的理由,那就開干!


做什么? 邁出第一步

這是做開源要想到的第一件事情,很多想做開源的同學,到這一步就想不下去了。還有同學,一上來就定位太高,做著做著發現根本做不出來,就提前放棄。做什么,看似簡單的問題,但是很重要的一步

不做什么

一些早期就知名的開源作品,很多都是因為作者在工作中遇到一個需求,而這個需求目前還沒有開源產品去滿足,因此自己做一個。但是對于我們大眾基層程序猿,天天寫業務代碼,重復勞動,你遇到這種需求的概率不是特別大。因此,這個方面就不在繼續往下討論了。

想要知道做什么,你就得先明白你做開源的一些期望,然后再去想做什么。我總結了兩點:

要快速做出第一版,至少能用。后面再慢慢迭代升級。 要能方便的推廣使用,最好是 0 成本使用。

做出來,推出去,要快。即,你做的快,別人用的也快。按照這種期望往下想,首先你能排除不做什么:

大型的框架,如做一個 UI 框架。 短期做不完,使用成本高 模擬成熟輪子,如在造一個 jQuery 。 有成熟方案,用戶不會換 小眾的東西。 基本沒人用 沒有特色,100% 的模仿。 用戶沒有更換的理由 做什么

排除以上這些,還剩下的范圍就不做了,我推薦做開源產品的方向:

小而精的工具。 開發快,使用成本低。 要有特色,哪怕是一個。 要和別人不一樣,差異化競爭。 一定要大眾,50% 以上的開發人員都會用到 避開已經被成熟產品壟斷的領域。 你就不要去跟 jQuery vue React 競爭了。

例如,前幾天 is-odd 在知乎鬧的沸沸揚揚,這個庫就是判斷奇數偶數,只不過考慮了各種數據類型的轉換。但是你看它的 weekly downloads 數量多大。

下面列舉幾個我認為比較合適做開源的例子:

cache 工具(緩存工具,整合 localStorage,以及合理的內存銷毀機制) query2json,解析 url 參數為 json 格式 移動端打印 console.log ,方便移動端輸出內容

其他符合上述條件的,根據自己當前的情況,大家可以自由發揮。最后,選擇哪個不重要,重要的是你選擇出來了。因此,如果你實在沒有合適的選擇,不如就從我舉例中選擇一個,抓鬮也行。選擇出來,你就可以繼續往下做了,否則你一直都在糾結。

本文將做什么

好了,本教程就確定要做一個 cache 工具,取一個性的名字,不和現有的重復(是否重復,去 github 一搜便知),叫做fast-cache


注冊賬號

注意,你如果現在已經有了 github 賬號,也不好忽略這一章的內容,很重要!

你一旦注冊一個 github 賬號并且去做開源產品,那你就要作為一個個人品牌持續運營下去,不能隨便改名字。因此注冊賬號時一定要慎重考慮,不能隨便弄一個,做一段時間又想改。

組織還是項目

首先,你要明確你即將注冊的賬號是專門針對一個產品(即項目賬號)還是將運維多個產品(即組織賬號)?

例如,facebook 就是 github 中的組織賬號,其下有很多開源產品,如 react 和 hhvm 等。而 rollup 就是 github 中的項目賬號,其下就一個項目 rollup ,其他的項目都是一些附件插件。

對于我們個人開發者,我推薦注冊項目賬號,即以你項目的名稱取個賬號的名字。這樣還有一個好處,就是后面講到官網的時候,你可以用更短、更好記的官網地址。例如,如果不自己申請域名、假設服務器(即不花一分錢)的情況下,以上例子中他們的官網有區別。

rollup 的官網地址將是 rollup.github.io ,很短; react 的官網地址只能是 facebook.github.io/react,多了一級目錄;(注意是不申請域名、不花錢的情況下)

最后,我選擇項目賬號,因此我需要注冊的賬號是 fast-cache

注冊賬號

我們分別要去 github 和 npm 注冊以 fast-cache 為用戶名的賬號,注冊過程就不寫了,都是傻瓜式操作。需要注意的是,如果被墻,自己想法辦科學上網

創建項目

登錄 github ,點擊右上角的“+”可看到新建項目的鏈接,或者直接訪問 https://github.com/new 。創建項目如下圖所示,注意圖中紅框部分。

圖片描述

創建完成之后,通過 https://github.com/fast-cache/fast-cache 即可訪問到項目的主頁,這是你就已經有了自己的開源項目了。

添加 ssh key

ssh key 就是連接你的電腦和 github 服務器的一把鑰匙,只有添加成功了才能把你本地的代碼提交到 github 服務器。

如果你是 mac os 系統,運行 ssh-keygen 即可一步一步生成 ssh key ,然后運行 pbcopy < ~/.ssh/id_rsa.pub 即可拷貝下來,等著粘貼。windows 系統用戶,自己百度搜索 github ssh key 即可找到相關介紹文章,跟著做就行了。

在 github 個人中心的設置界面,能找到 SSH and GPS keys 菜單欄,或者直接訪問 https://github.com/settings/keys 。頁面中點擊右側“new ssh key”按鈕即可添加 ssh key ,把剛才的內容粘貼過來添加上就行了。

下載代碼

進入 github 項目主頁,復制 git 地址(注意選擇 use ssh ,不要 use https ),如下圖

圖片描述

復制下來的內容應該是 [email protected]:fast-cache/fast-cache.git ,然后你選擇一個合適的文件夾或目錄,執行下載命令。

  1. git clone [email protected]:fast-cache/fast-cache.git
復制代碼

下載完畢,進入代碼目錄,運行如下命令修改當前 git 的用戶名和郵箱,改成和當前 github 用戶名和注冊郵箱一致。

  1. cd fast-cache
  2. git config user.name 'fast-cache'
  3. git config user.email '[email protected]'
復制代碼

最后,隨便修改一下 README.md 文件的內容,然后提交,看能否成功?成功了就說明剛才的ssh key 生效了。

  1. git add .
  2. git commit -m "first update"
  3. git push origin master
復制代碼

搭建開發環境 初始化

進入項目目錄,然后命令行運行 npm init ,按照提示進行初始化即可。提示中的信息,能寫的都寫上,別隨意忽略了。初始化完成之后,項目根目錄下會有 package.json 的文件。

規范版本號

打開 package.json 文件,將版本號定義為 "version": "0.0.1" 。以后我們每次正式提交代碼,版本號都不一樣。版本號分三級,分別為:

一級,重構版本 二級,重大功能改進 三級,小升級或者 bug 修復

為何從 0.0.1 開始?因為 0.x.x 可以認為是非正式版本、測試版,而從 1.x.x 開始,就是正式發布的版本了。

規范一級目錄

項目的一級目錄要提前規范好,最起碼一些常用的目錄要提前訂好留用,不能亂來。例如:

src - 源代碼 release - 發布結果 test - 單元測試用例 doc - 文檔 example - 示例 構建工具

這部分比較獨立,內容也比較多,就不詳細講了,用最常用的 webpack 做一個簡單演示吧。

安裝插件 npm i babel-core babel-loader babel-polyfill babel-preset-es2015 babel-preset-latest webpack webpack-cli --save-dev

項目根目錄下創建 .babelrc 文件,內容如

  1. {
  2. "presets": ["es2015", "latest"],
  3. "plugins": []
  4. }
復制代碼

項目根目錄下創建 webpack.config.js 文件,內容如

  1. module.exports = {
  2. entry: './src/index.js',
  3. output: {
  4. path: __dirname,
  5. filename: './release/bundle.js'
  6. },
  7. module: {
  8. rules: [{
  9. test: /\.js?$/,
  10. exclude: /(node_modules)/,
  11. loader: 'babel-loader'
  12. }]
  13. }
  14. }
復制代碼

最后,修改 package.json 中的 scripts ,增加 "release": "webpack" 。然后命令行運行 npm run release ,就可生成 release 的內容。

運行示例

release 的內容已經發布出來了,還要運行起來,最簡單的方式,在example創建test.html,然后引用 release 的內容。

  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4. <meta charset="UTF-8">
  5. <title>example</title>
  6. </head>
  7. <body>
  8. <p>example</p>
  9. <script src="../release/bundle.js"></script>
  10. </body>
  11. </html>
復制代碼

為何規范化運行,可以修改 package.json 中的 scripts ,增加 "example": "http-server -p 8880" 。然后命令行運行 npm run example ,瀏覽器訪問 http://localhost:8880/example/test.html

規范 git 分支

至少要存在兩個分支,masterdevdev 是開發中的代碼。當然,你可以規范更多的分支,例如 next fix-bug 等,但是注意一個原則 —— 用不到的就先不要規劃

完善 README.md

README.md 是開源項目的一張臉,用戶的第一印象。必須包含以下內容:

產品簡介(此處要突出特點,打差異化競爭) 產品安裝和下載 快速使用(詳細的使用文檔或者二次開發文檔,外鏈即可) 交流提問區 關于作者(放你的博客鏈接,和收款二維碼)

最后,把以上完成的工作,都提交到 github 中。


提交代碼 寫代碼

具體寫什么代碼不是本文的重點,你盡情的根據自己的項目來寫自己的代碼就是了。記得一定要使用編碼規范的工具,例如 es-lint 等,否則經過長時間的維護,必然留坑。

寫文檔 & 寫測試用例

注意,文檔和測試用例對于一個開源產品來說非常重要!非常重要!非常重要!而且,文檔和測試用例本身就是代碼不可分割的一部分

如何寫測試用例,需要用到其他工具,內容也相對獨立,這里就不介紹了,自己去查一查吧。再次強調,測試用例很重要!!!

在寫文檔之前,還需要準備其他的工具。定位到項目目錄下,npm i gitbook-cli -g 安裝 gitbook ,然后創建 SUMMARY.md ,內容如下:

  1. # Summary
  2. * [項目介紹](README.md)
  3. * [使用文檔](doc/use/README.md)
  4. * [使用1](doc/use/use1.md)
  5. * [使用2](doc/use/use2.md)
  6. * [二次開發](doc/dev/README.md)
  7. * [開發1](doc/dev/dev1.md)
  8. * [開發2](doc/dev/dev2.md)
復制代碼

其實一看這個文件內容就知道,這是一個文檔的目錄,你可以根據自己項目的需要重新定義這個目錄。需要注意的是,第一行 * [項目介紹](README.md) 對應的是已經存在的 README.md 文件。

運行 gitbook init ,會看到各個文件都被創建了,就可以完善各個文檔的內容。內容完成之后,運行 gitbook build 可以將 md 文件發布為 html 文件,默認放在 _book 文件夾。啟動了 npm run example 之后,可以訪問 http://127.0.0.1:8880/_book/ 查看效果。

最后,再次修改一下 README.md ,把文檔的鏈接加上

  1. [如何使用](./doc/use/README.md) [二次開發](./doc/dev/README.md)
復制代碼
提交第一版代碼

首先,修改一下 .gitignore 文件,加上一行 _book ,把打包出來的文件忽略掉。然后用之前的方式提交到 github 的 master 分支,這里不再贅述了。

接下來,創建 tag 并提交,代碼如下:

  1. git tag -a 'v0.0.1' -m 'first commit'
  2. git push origin v0.0.1
復制代碼

提交之后,下載地址就有了 , https://github.com/fast-cache/fast-cache/releases 這里可以下載到各個版本的源碼。

最后要提交到 npm 上,能讓使用者通過 npm 進行安裝。首先,運行 npm add usernpm login 來登錄,根據提示將你之前注冊 npm 時的賬號、密碼、郵箱寫上就行了,問題不大。然后,在項目的根目錄運行 npm publish .此時問題來了!!!

運行之后報了 403 錯誤,剛才明明登錄成功了,不可能有權限問題呀。后來一查才知道,原來 fast-cache 在 npm 中和其他項目重名了!!!沒辦法,只能改名,將 package.json 中的名稱改為 fast-cache-npm ,然后再發布就成功了。

發布之后,通過 https://www.npmjs.com/package/fast-cache-npm 就可以訪問 npm 項目主頁了。

注意,為項目取名時,一定要提前把名字在 github 和 npm 搜索一下,確認沒有重名才行!!!

升級代碼并提交

上述是第一次提交代碼的流程,下面簡述一下升級代碼之后的提交流程。在代碼開發階段的步驟總結如下:

來一個 dev 分支,不要在 master 分支開發 修改 package.json 版本號,按照之前既定的版本規則修改,不能亂改 修改代碼、文檔和測試用例 自測 將 dev 分支提交到遠程

代碼開發完成之后,提交的流程如下:

再次確認版本號,因為版本號非常重要 將 dev 合并到 master ,并提交 master 到遠程 創建 tag 并提交到遠程 提交到 npm 合并 pr

pr 即 Pull Request 的簡稱。

開源軟件最大的特色就是允許全世界的開發者都能為其貢獻代碼,你這個開源項目也不例外。其他人很有可能會通過 github 的 pr 為你的項目貢獻自己的代碼,到時候你既得欣然接受,又不能茫然接受。

其他人貢獻的 pr 可以通過 https://github.com/fast-cache/fast-cache/pulls 鏈接看到。對于每一個 pr ,如果你想合并,直接 merge 就好了(合并完之后,本地代碼要隨時更新一下);如果你不想合并,留言說明然后關閉掉即可。


創建官網

我們通過 github pages 的機制即可免費創建項目的掛網,不用花一分錢。

創建項目

登錄 github ,創建一個名為 fast-cache.github.io 的項目,名字必須是這一個!!!然后下載到本地,即 git clone xxxx 。然后,進入項目目錄,新建一個 index.html ,然后隨便寫點什么,例如

hello world

,提交到 github 遠程。

最后,訪問 fast-cache.github.io ,你就能看到剛才的內容了,最簡單的官網就這么出來了。做到這里,你應該知道 github pages 就是一個靜態頁面的服務器,上傳相應的 html 就能顯示。

生成官網

此前用 gitbook 將文檔生成為 html 了,應該還記得。那么我們現在重新運行 gitbook build 生成 html ,然后將所有的 html 拷貝到這里來,全部提交上去,正式的官網也就出來了。

圖片描述

更新 README.md

記得要修改 README.md ,把官網的地址加進去。


如何宣傳

“酒香不怕巷子深”這句話在當代并不適用,特別是互聯網中。我在 N 年前看過一本創業公司老板寫的研發項目管理方面的書,到現在就記住一句話 —— “一個公司的核心競爭力,一是技術,二是營銷”。因此,雖然是一個簡單的開源項目,宣傳也是必須必要的。

宣傳和更新維護都是一個漫長的過程,作為屌絲賬戶的我們(不是 google facebook 等明星賬戶),能做的只能是堅持。

寫博客

首先,要圍繞著你做的產品功能來寫博客。例如針對 fast-cache ,我們可以寫類似這樣的博客。分體分兩類,第一類是相關的技術干貨文章,第二類是產品介紹,應該以第一類為主。

總結如何做前端緩存 前端緩存的坑 預防前端內存泄露 前端緩存插件 fast-cache使用總結 fast-cache 開發半年記 ……

其次,要正確選擇發表的網站,我的建議是這樣的:

選擇一個地方作為你博客的唯一主頁,例如 github ,像創建官網一樣創建個人博客網站。 博客貼到各大博客網站,如掘金、知乎專欄、博客園。選擇三個流量較大的即可,不用到處亂貼。 博客內容要寫明白原文的鏈接,并寫明產權。 最好能找到一些媒體(如 InfoQ)或者大牛公眾號幫你轉發。 回答相關問題

去知乎、sf.gg 甚至是 stackoverflow 上面去搜索、關注與你產品相關的問題,積極參與回答。回答問題也有技巧:

字數只能多不能少。最好圖文并茂,還能講個笑話 回答要專業,經過親自測試,不要想當然的瞎猜 回答問題的最后,順便推廣自己的產品 口碑宣傳

所謂口碑宣傳就是讓用戶資源的幫助宣傳,那就需要把產品做好,那如何做“好”呢?

明確產品定位,有特色。做“T”型產品,差異化競爭。把一方面做好就行了,所有都做好不可能。 及時回復問題,定期更新升級,做好升級計劃,讓用戶看到產品在不管進步和變化。
持續迭代

主要來探討一下如何有效率的持續迭代,再不影響工作、生活的情況下。

統一問題收集區

這一點非常重要!!! 因為:

你沒有那么多精力去很多個平臺回復問題 你沒有那么多時間天天盯著 QQ 群解答問題 問題應該被集中起來,供使用者反復查閱

例如 wangEditor 的問題收集區主要集中在 github issue 列表,其他的地方的提問直接忽略。還有一點要特別注意,問題應該本分享,而不是私聊,因此如下提問方式直接忽略:

QQ 群提問和 QQ 私聊提問(或微信) 私信提問 郵件提問

回顧我前幾年剛做開源的經歷,一開始你和使用者都會非常不習慣這種方式,特別是那些討厭的伸手黨。剛開始進來的用戶直接 QQ 私聊或者群里 @ 你,讓你做他們的技術客服,隨叫隨到,這種人你一定要堅持不理會,然后引導他們去 github 提交 issue 。慢慢的,你的社區和 QQ 群人多了,大家都知道這個套路,再有新人進來會自動被引導到 github 中提交 issue 。

定期答復和升級

讓別人自愿、積極的去提交 issue 的前提是你能及時的答復。根據我的經驗,給你以下建議:

定期回復 每天(下班或者上班之前)看看 github issues 然后先答復,臨時無法搞清楚的就回復“周末時看下再答復”。這樣每天大約花費 5-15 分鐘即可,出去抽根煙的功夫。最后,需要修改的問題,先記錄下。 定期升級 每周拿出 2 個小時(隨便一個晚上或者周末時間)把記錄下的問題,按照優先級高低順序修復。就 2 小時,改多少算多少,改不完下周再說。改完的問題要及時回復 issue 并 close 。每周 2 小時,對你這周的工作生活應該不會受到影響。 學會拒絕

當用戶慢慢增多,用戶會提出各種看似奇葩的需求,以滿足他們自己的使用需要。此時就需要你來分辨該需求是否應該被添加。我總結了以下判斷標準:

很多用戶都提過這個需求,即大眾需求 你自己判斷這個需求對大部分用戶都有用 該需求符合產品定位以及產品發展的方向 該需求能抹平和競品的差距,或者能和競品差異化競爭

符合以上要求的,可以加入升級計劃。不符合要求的,你一定要無情拒絕,此時不要做好人。

持之以恒

雖然每天十幾分鐘、每周兩小時看似不占用太多時間,但是你要持之以恒的堅持一年、兩年、三年,你能做到嗎?

你做任何什么事情,沒點持之以恒的態度,都做不成功。


總結

回顧一下本課程的重點內容:

做開源的意義。不是套話,你意識不到,肯定就做不下去; 開源項目是什么。不僅僅是源碼。 做什么。小而精,不要大而全。 怎么做? 宣傳和持續迭代


回復

使用道具 舉報