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

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

限于篇幅，本文很多點都是點到為止，文章中有大量鏈接供同學進一步了解掌握相關知識。

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

我們首先要提的是 README 文檔，這是每個開源項目所必須的，README 文檔會默認展示在項目首頁，可以算作是整個項目的門面。一個靠譜的 README 應該包含以下幾部分：

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

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

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

隨著你的項目日趨復雜，也許 README 的篇幅已經不能夠承載你的 API 說明，這時在項目中多帶帶建立一個 doc 文件夾用來存放文檔，也是很多人的選擇。

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

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

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

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

除了在 README 中提到遵循的開源協議外，一個靠譜的開源項目還會將該開源協議的內容文檔放在自己的項目下方。

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

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

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

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

這是一份有著很長歷史的，由一群經驗豐富的 js 工程師維護的代碼風格規范，同時也十分通俗易懂，另外他也有簡體中文的版本。

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

jQuery 所倡導和使用的代碼規范，大量的 jQuery 組件根據這一規范書寫，如果你讀過 jQuery 的源碼，你喜歡他的風格，或者你正在開發一款 jQuery 的插件，那這也是一個不錯的選擇。

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

谷歌倡導的代碼風格，自 2012 年推出以后已經有很多谷歌的項目遵循這份規范進行編碼，喜歡谷歌風格的朋友可以使用。

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

在這里我們要推薦 ESLint 這款工具。在不久之前，你還有另一個選擇 JSCS，但在最近，JSCS 團隊選擇與 ESLint 團隊進行合并，專注于一款產品 ESLint 的開發，兩大大牛團隊的合體想必會帶給 ESLint 更為強大的生命。

圖1：JSCS 與 ESLint 已經合并

ESlint 提供了非常豐富的 IDE 集成工具，目前已經支持 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

這里會有一些人機交互，來選擇 eslint 的風格，之后 eslint 就會在你的項目下添加對應的依賴，重啟 sublime，就可以看到效果了。

圖2：eslint sublime 插件演示

我們可以看到，linter 對于不符合規則的行和代碼塊會標紅，將鼠標點擊到對應標紅的塊，會顯示報錯的原因，比如上圖中是因為 (global-require) 規則。有時僅通過提示的錯誤文案，無法幫你準確理解含義，這時我們還可以借助 eslint 的站點：http://eslint.org/docs/rules/ ，這里有更詳細的講解，你還可以直接搜索對應的規則。

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

一個測試體系大體應該包含以下三部分，這三者功能上互相獨立，但合作完成一次測試：

測試運行器(Test runner)：主要負責測試的自動化，主要負責調用測試框架和測試代碼，自動打開瀏覽器或者 js 環境，執行測試。

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

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

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

# 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".

然后就可以運行了

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

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

測試框架有很多:

mocha

jasmine

qunit

Jest

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

首先安裝 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));
    });
  });
});

運行 test，查看結果

mocha test/test.js

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

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

expect.js

should

chai

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

3.4.1 測試模式

有人會問 BDD 和 TDD 都代表了什么？

TDD

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

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)，即 行為驅動開發。

通常 BD測試提供了幾個方法:

describe()

it()

before()

after()

beforeEach()

afterEach()

通過這些方法描述一種行為，當測試的表現滿足行為的預期時，即表示測試通過。

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

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

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

兩者都是接入 Github 的持續集成工具，其核心是通過一個腳本，在代碼 commit 的時候自動運行繼承腳本，完成測試、構建等任務。以 Travis CI 為例，首先在 github 的 Travis CI 頁面將 Travis CI 的 hook 加入到你的項目中。

圖3：將 Travis CI/CircleCI 集成到你的項目中。

接著在你的項目目錄下建立一個 .travis.yml，大致長成這個樣子：

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 會自動執行 npm install 和 npm test 來進行集成測試。更多的配置可以參考官方的文檔。集成通過在兩個地方可以有所體現：

一個是 ci 提供的 badge：

一個是在 pr 提交時的自動 comment

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

saucelabs 也提供了很棒的 badge

代碼覆蓋率可以在本地測試里集成，同樣也可以在 CI 中集成，通過引入 Coveralls，他可以將你持續集成測試中得到的代碼覆蓋率結果做一個記錄和保存，同時及時的反饋給用戶。

Coveralls 也有兩個地方可以體現：

一個是 Coveralls 提供的 badge：

一個是在 pr 提交時的自動 comment

圖4：coveralls 的自動 comment

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

慣例地來宣傳一下團隊開源的 React PC 組件庫 UXCore ，上面提到的點，在我們的組件開發工具中都有體現，歡迎大家一起討論，也歡迎在我們的 SegmentFault 專題下進行提問討論。

本文作者 eternalsky，始發于團隊微信公眾號 猿猿相抱 和 segmentFault 專欄 UXCore，轉載請保留作者信息。