摘要：一個(gè)靠譜的應(yīng)該包含以下幾部分言簡意賅的項(xiàng)目介紹你的項(xiàng)目解決了什么核心問題，有哪些令人心動(dòng)的特性。除了在中提到遵循的開源協(xié)議外，一個(gè)靠譜的開源項(xiàng)目還會(huì)將該開源協(xié)議的內(nèi)容文檔放在自己的項(xiàng)目下方。

寫前端代碼一段時(shí)間之后，你可能會(huì)萌生做一個(gè)開源項(xiàng)目的想法，一方面將自己的好點(diǎn)子分享出去讓更多的人受益，另一方面也可以在社區(qū)貢獻(xiàn)的環(huán)境下學(xué)到更多的東西從而快速成長。但是開源項(xiàng)目也有開源項(xiàng)目的玩法，一些可能沒有注意的點(diǎn)，也許會(huì)讓你的好點(diǎn)子和許多人失之交臂，在這里筆者以自身經(jīng)驗(yàn)出發(fā)，聊一聊筆者心目中的靠譜的 Github 前端開源項(xiàng)目應(yīng)該具有什么。當(dāng)然我們討論的只是一個(gè)項(xiàng)目至少需要什么才是靠譜的。真的想要做好一個(gè)項(xiàng)目，需要的比這里要講的多得多。

限于篇幅，本文很多點(diǎn)都是點(diǎn)到為止，文章中有大量鏈接供同學(xué)進(jìn)一步了解掌握相關(guān)知識(shí)。

文檔是你的潛在用戶了解項(xiàng)目的第一道窗口，文檔書寫的好壞直接決定了項(xiàng)目的易用性和用戶粘性。

我們首先要提的是 README 文檔，這是每個(gè)開源項(xiàng)目所必須的，README 文檔會(huì)默認(rèn)展示在項(xiàng)目首頁，可以算作是整個(gè)項(xiàng)目的門面。一個(gè)靠譜的 README 應(yīng)該包含以下幾部分：

言簡意賅的項(xiàng)目介紹：你的項(xiàng)目解決了什么核心問題，有哪些令人心動(dòng)的特性。

簡單的安裝和使用指導(dǎo)：用戶如何安裝你的項(xiàng)目，又如何使用在自己的項(xiàng)目中，你應(yīng)該想辦法讓這部分盡量簡單，降低接受成本。

API 和配置說明：也許你的項(xiàng)目十分強(qiáng)大，支持很多特性，你需要告訴用戶如何通過配置和 API 來完成這些事情，在這中間，也許你可以插入一些簡單的 demo，幫助用戶理解，這部分的好壞直接決定了項(xiàng)目的易用性。

隨著你的項(xiàng)目日趨復(fù)雜，也許 README 的篇幅已經(jīng)不能夠承載你的 API 說明，這時(shí)在項(xiàng)目中多帶帶建立一個(gè) doc 文件夾用來存放文檔，也是很多人的選擇。

如何貢獻(xiàn)：開源的一個(gè)很重要的目的是為了讓社區(qū)中的更多人來幫助你完善你的創(chuàng)意，你需要告訴他們你有哪些部分是他們可以幫的上忙的，你是如何對(duì)待 issues 和 pull requests( 后文稱 pr) 的。

如何與作者取得聯(lián)系：有些合作和洽談可能無法承載在 issue 上，告訴用戶除了 issues，還有什么途徑可以與作者取得聯(lián)系。

開源許可協(xié)議：既然是一個(gè)開源項(xiàng)目，那么開源許可協(xié)議必然是不可少的，你的開源許可是 MIT、BSD 還是 ISC、Apache？當(dāng)然你也需要了解這些開源許可的意義，這里推薦一篇知乎問答。

上面我們也提到了如何貢獻(xiàn)的問題，當(dāng)貢獻(xiàn)需要了解的東西越來越多的時(shí)候，我們也習(xí)慣于把它多帶帶抽成一份 CONTRIBUTING.md。在貢獻(xiàn)文檔中應(yīng)該詳細(xì)地告訴貢獻(xiàn)者，哪些功能點(diǎn)是需要貢獻(xiàn)者參與的，如何提 issue 以及 pr。

除了在 README 中提到遵循的開源協(xié)議外，一個(gè)靠譜的開源項(xiàng)目還會(huì)將該開源協(xié)議的內(nèi)容文檔放在自己的項(xiàng)目下方。

關(guān)于代碼風(fēng)格，每個(gè)人可能都會(huì)有自己的偏好，這些偏好中有好的，也有壞的，一些不好的代碼風(fēng)格會(huì)讓其他開發(fā)者感到不快，減少了大家對(duì)于代碼的關(guān)注，好在強(qiáng)大的開源社區(qū)中同樣也有人開源了代碼風(fēng)格規(guī)范，這些代碼規(guī)范都經(jīng)過了激烈的討論和充分的修改，為大多數(shù)人所認(rèn)可，需要注意的是代碼風(fēng)格并不只是縮進(jìn)、空格這一類的事情，它更多地是一種代碼習(xí)慣，比如何時(shí)使用 const，何時(shí)使用 let，是否有聲明但未使用的變量等等，這些習(xí)慣并不影響代碼的功能，卻可以很大程度上決定代碼的可維護(hù)性、易讀性和降低犯錯(cuò)的機(jī)會(huì)，同時(shí)也讓其他開發(fā)者對(duì)你的項(xiàng)目刮目相看。

2.1.1 Airbnb: https://github.com/airbnb/jav...

Airbnb 的 js 規(guī)范應(yīng)該是目前受認(rèn)可度最高的代碼規(guī)范之一，目前在 Github 上已經(jīng)累加了 36700+ 顆星，包含的領(lǐng)域非常廣泛，包括線下時(shí)髦的 ES6 和 React JSX 等等，筆者推薦。

2.1.2 idiomatic.js: https://github.com/rwaldron/i...

這是一份有著很長歷史的，由一群經(jīng)驗(yàn)豐富的 js 工程師維護(hù)的代碼風(fēng)格規(guī)范，同時(shí)也十分通俗易懂，另外他也有簡體中文的版本。

2.1.3 jQuery：https://contribute.jquery.org...

jQuery 所倡導(dǎo)和使用的代碼規(guī)范，大量的 jQuery 組件根據(jù)這一規(guī)范書寫，如果你讀過 jQuery 的源碼，你喜歡他的風(fēng)格，或者你正在開發(fā)一款 jQuery 的插件，那這也是一個(gè)不錯(cuò)的選擇。

2.1.4 Google：https://google.github.io/styl...

谷歌倡導(dǎo)的代碼風(fēng)格，自 2012 年推出以后已經(jīng)有很多谷歌的項(xiàng)目遵循這份規(guī)范進(jìn)行編碼，喜歡谷歌風(fēng)格的朋友可以使用。

看到這里有人會(huì)有疑問，規(guī)范雖然好，可是條目太多了，我雖然可以學(xué)習(xí)，但是全都記住難度太高了。不用擔(dān)心，你的痛點(diǎn)也是大家的痛點(diǎn)，早已經(jīng)有工具幫助我們來解決這一問題，而且更棒的是他可以無縫地與你的 IDE 相結(jié)合。

在這里我們要推薦 ESLint 這款工具。在不久之前，你還有另一個(gè)選擇 JSCS，但在最近，JSCS 團(tuán)隊(duì)選擇與 ESLint 團(tuán)隊(duì)進(jìn)行合并，專注于一款產(chǎn)品 ESLint 的開發(fā)，兩大大牛團(tuán)隊(duì)的合體想必會(huì)帶給 ESLint 更為強(qiáng)大的生命。

圖1：JSCS 與 ESLint 已經(jīng)合并

ESlint 提供了非常豐富的 IDE 集成工具，目前已經(jīng)支持 Sublime Text 3, Vim, Emacs, Eclipse, TextMate 2, Atom, IDEA 和 Visual Studio Code。具體的插件工具請移步 ESlint 的集成文檔。下面我們以 sublime 為例，簡單講一下如何使用這些插件：

首先全局安裝 ESLint：

npm install -g eslint

接著通過 Package Control，安裝 SublimeLinter 和 SublimeLinter-contrib-eslint。

初始化 eslint 配置

eslint --init

這里會(huì)有一些人機(jī)交互，來選擇 eslint 的風(fēng)格，之后 eslint 就會(huì)在你的項(xiàng)目下添加對(duì)應(yīng)的依賴，重啟 sublime，就可以看到效果了。

圖2：eslint sublime 插件演示

我們可以看到，linter 對(duì)于不符合規(guī)則的行和代碼塊會(huì)標(biāo)紅，將鼠標(biāo)點(diǎn)擊到對(duì)應(yīng)標(biāo)紅的塊，會(huì)顯示報(bào)錯(cuò)的原因，比如上圖中是因?yàn)?(global-require) 規(guī)則。有時(shí)僅通過提示的錯(cuò)誤文案，無法幫你準(zhǔn)確理解含義，這時(shí)我們還可以借助 eslint 的站點(diǎn)：http://eslint.org/docs/rules/ ，這里有更詳細(xì)的講解，你還可以直接搜索對(duì)應(yīng)的規(guī)則。

靠人工來保證項(xiàng)目的維護(hù)總是不出差錯(cuò)是不靠譜的，人總有健忘和糊涂的時(shí)候，尤其是當(dāng)項(xiàng)目越來越復(fù)雜時(shí)，一個(gè)人甚至可能無法全部了解項(xiàng)目的全部邏輯，這時(shí)我們就要依靠測試來保證項(xiàng)目的可靠性，這里的測試包括但不限于，單元功能測試，UI 測試，兼容性測試等等。

一個(gè)測試體系大體應(yīng)該包含以下三部分，這三者功能上互相獨(dú)立，但合作完成一次測試：

測試運(yùn)行器(Test runner)：主要負(fù)責(zé)測試的自動(dòng)化，主要負(fù)責(zé)調(diào)用測試框架和測試代碼，自動(dòng)打開瀏覽器或者 js 環(huán)境，執(zhí)行測試。

測試框架(Testing Framework)：測試框架規(guī)定了測試風(fēng)格和測試的生命周期(lifeCircle hook)。

斷言庫(Assertion library)：每個(gè)測試單元是通過一句或者一組斷言來組成的，每一句斷言聲明了對(duì)一種功能的描述。例如 expect(window.r).to.be(undefined);。

一個(gè)優(yōu)秀的 runner 可以做很多事情，我們以 Google Angular 團(tuán)隊(duì)推出的 karma 為例，你可以指定在什么瀏覽器中，使用什么測試框架，進(jìn)一步地完成測試框架的配置，以及其他非常多的定制。他的安裝和初始化也非常簡單：

# Install Karma:
$ npm install karma --save-dev

# Install plugins that your project needs:
$ npm install karma-jasmine karma-chrome-launcher --save-dev

初始化配置文件

$ karma init my.conf.js

Which testing framework do you want to use?
Press tab to list possible options. Enter to move to the next question.
> jasmine

...

Do you want Karma to watch all the files and run the tests on change?
Press tab to list possible options.
> yes

Config file generated at "/Users/vojta/Code/karma/my.conf.js".

然后就可以運(yùn)行了

# Run Karma:
$ ./node_modules/karma/bin/karma start

當(dāng)然這只是最初始化的配置，我們還沒有寫真正的測試，所以這里只是一個(gè)空架子。

測試框架有很多:

mocha

jasmine

qunit

Jest

對(duì)于一般的開發(fā)者來說，他們都能夠滿足日常的測試需求，所以主要看你的使用習(xí)慣，這里以 mocha 為例來給大家一個(gè)大概的印象。

首先安裝 mocha

$ npm install -g mocha
$ mkdir test
$ $EDITOR test/test.js

接下來寫你的 test

var assert = require("chai").assert;
describe("Array", function() {
  describe("#indexOf()", function () {
    it("should return -1 when the value is not present", function () {
      assert.equal(-1, [1,2,3].indexOf(5));
      assert.equal(-1, [1,2,3].indexOf(0));
    });
  });
});

運(yùn)行 test，查看結(jié)果

mocha test/test.js

當(dāng)然上面這個(gè)測試只能測試 node 下的 js 代碼，如果你的代碼是前端項(xiàng)目，那么就要借助 phantom/browser 等工具了，同時(shí)操作這么多東西很麻煩，這時(shí) karma 的作用的就體現(xiàn)出來了，本文只是大體的介紹，因此不再鋪開去講，詳細(xì)請查看 karma 的官方文檔。

斷言庫也有很多的選擇，其中比較有名氣的有：

expect.js

should

chai

其中，chai 同時(shí)支持 BDD 和 TDD 兩種測試模式，而 expect.js 具有 IE6+ 級(jí)別的瀏覽器兼容性。

3.4.1 測試模式

有人會(huì)問 BDD 和 TDD 都代表了什么？

TDD

TDD(Test-driven development)，即 測試驅(qū)動(dòng)開發(fā)。即先根據(jù)需求寫測試，然后再寫代碼，使代碼逐漸符合測試要求，不符合時(shí)重構(gòu)代碼滿足。這種開發(fā)模式適合一些需求非常清晰明確，且不再變更的情況，在一般的開發(fā)中，我們還是 BDD 的模式使用的比較多。chai 提供的 assert 部分是經(jīng)典的 TDD 風(fēng)格，大致如下

var assert = require("chai").assert
  , foo = "bar"
  , beverages = { tea: [ "chai", "matcha", "oolong" ] };

assert.typeOf(foo, "string"); // without optional message
assert.typeOf(foo, "string", "foo is a string"); // with optional message
assert.equal(foo, "bar", "foo equal `bar`");
assert.lengthOf(foo, 3, "foo`s value has a length of 3");
assert.lengthOf(beverages.tea, 3, "beverages has 3 types of tea");

BDD

BDD(Behavior-Driven development)，即 行為驅(qū)動(dòng)開發(fā)。

通常 BD測試提供了幾個(gè)方法:

describe()

it()

before()

after()

beforeEach()

afterEach()

通過這些方法描述一種行為，當(dāng)測試的表現(xiàn)滿足行為的預(yù)期時(shí)，即表示測試通過。

持續(xù)集成，continuous integration (簡稱 ci)，指的是頻繁地（一天多次）將代碼集成到主干。

為了保證這種快速迭代的開發(fā)方式不出差錯(cuò)，采取的核心措施：代碼集成到主干之前，必須通過自動(dòng)化測試。只要有一個(gè)測試用例失敗，就不能集成。這種行為雖然不能消除 bug，但有效地幫助我們即時(shí)發(fā)現(xiàn)錯(cuò)誤并改正。關(guān)于持續(xù)集成的詳細(xì)流程，大家參考阮老師的 持續(xù)集成是什么？。本文則重點(diǎn)介紹已經(jīng)介入 github，可以幫助到我們的繼承工具。

接入到 github 的所有 CI 可以在 https://github.com/integrations 中查看。

兩者都是接入 Github 的持續(xù)集成工具，其核心是通過一個(gè)腳本，在代碼 commit 的時(shí)候自動(dòng)運(yùn)行繼承腳本，完成測試、構(gòu)建等任務(wù)。以 Travis CI 為例，首先在 github 的 Travis CI 頁面將 Travis CI 的 hook 加入到你的項(xiàng)目中。

圖3：將 Travis CI/CircleCI 集成到你的項(xiàng)目中。

接著在你的項(xiàng)目目錄下建立一個(gè) .travis.yml，大致長成這個(gè)樣子：

language: node_js

sudo: false

notification:
  email:
    - xxx@hotmail.com

node_js:
- 4.0.0

env:
  matrix:
  - TEST_TYPE=test
  - TEST_TYPE=coverage
  - TEST_TYPE=saucelabs

在不指定 .travis.yml 的情況下，travis 會(huì)自動(dòng)執(zhí)行 npm install 和 npm test 來進(jìn)行集成測試。更多的配置可以參考官方的文檔。集成通過在兩個(gè)地方可以有所體現(xiàn)：

一個(gè)是 ci 提供的 badge：

一個(gè)是在 pr 提交時(shí)的自動(dòng) comment

這兩個(gè)工具都是提供了多種瀏覽器環(huán)境，包括 pc 端和移動(dòng)端，然后在多種環(huán)境下都是去運(yùn)行測試腳本，來測試項(xiàng)目的瀏覽器兼容性。其中 SAUCELABS 對(duì)于開源項(xiàng)目完全免費(fèi)，只需要走他的 Open Source Plan 即可，而 Browser Stack 雖然也提供了 Open Source 的免費(fèi)計(jì)劃，但比較麻煩，需要郵件聯(lián)系，并且在項(xiàng)目 README 中提到其對(duì)項(xiàng)目的支持。手動(dòng)配置這些集成還是比較麻煩的，一般我們都借助 karma 來集成，使用 karma 的 karma-saucelabs-launcher 和 karma-browserstack-launcher。

saucelabs 也提供了很棒的 badge

代碼覆蓋率可以在本地測試?yán)锛桑瑯右部梢栽?CI 中集成，通過引入 Coveralls，他可以將你持續(xù)集成測試中得到的代碼覆蓋率結(jié)果做一個(gè)記錄和保存，同時(shí)及時(shí)的反饋給用戶。

Coveralls 也有兩個(gè)地方可以體現(xiàn)：

一個(gè)是 Coveralls 提供的 badge：

一個(gè)是在 pr 提交時(shí)的自動(dòng) comment

圖4：coveralls 的自動(dòng) comment

礙于篇幅有限和行文的目的，文中提供的很多點(diǎn)，只是舉了一些例子，點(diǎn)到為止，同時(shí)提供了鏈接，供大家日后仔細(xì)研究。作者希望通過此文，讓讀者了解到一個(gè)靠譜的前端開源項(xiàng)目應(yīng)該具備的東西，這個(gè)靠譜不僅是為了讓用戶用的放心，更是為了開發(fā)者在開發(fā)時(shí)心中有譜。那具備了這些就代表了一個(gè)成功的開源項(xiàng)目嗎？很遺憾，這只是通往成功的必備條件，一個(gè)成功的開源項(xiàng)目還需要開發(fā)者更多的經(jīng)營，最重要的，是一份為用戶解決痛點(diǎn)的初衷和持之以恒的決心。

慣例地來宣傳一下團(tuán)隊(duì)開源的 React PC 組件庫 UXCore ，上面提到的點(diǎn)，在我們的組件開發(fā)工具中都有體現(xiàn)，歡迎大家一起討論，也歡迎在我們的 SegmentFault 專題下進(jìn)行提問討論。

本文作者 eternalsky，始發(fā)于團(tuán)隊(duì)微信公眾號(hào) 猿猿相抱 和 segmentFault 專欄 UXCore，轉(zhuǎn)載請保留作者信息。