一個靠譜的前端開源項目須要什麼？

0. 前言

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

限於篇幅，本文不少點都是點到爲止，文章中有大量連接供同窗進一步瞭解掌握相關知識。

1. 文檔

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

1.1 README

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

• 言簡意賅的項目介紹：你的項目解決了什麼核心問題，有哪些使人心動的特性。
• 簡單的安裝和使用指導：用戶如何安裝你的項目，又如何使用在本身的項目中，你應該想辦法讓這部分儘可能簡單，下降接受成本。
• API 和配置說明：也許你的項目十分強大，支持不少特性，你須要告訴用戶如何經過配置和 API 來完成這些事情，在這中間，也許你能夠插入一些簡單的 demo，幫助用戶理解，這部分的好壞直接決定了項目的易用性。

隨着你的項目日趨複雜，也許 README 的篇幅已經不可以承載你的 API 說明，這時在項目中單獨創建一個 doc 文件夾用來存放文檔，也是不少人的選擇。

• 如何貢獻：開源的一個很重要的目的是爲了讓社區中的更多人來幫助你完善你的創意，你須要告訴他們你有哪些部分是他們能夠幫的上忙的，你是如何對待 issues 和 pull requests( 後文稱 pr) 的。
• 如何與做者取得聯繫：有些合做和洽談可能沒法承載在 issue 上，告訴用戶除了 issues，還有什麼途徑能夠與做者取得聯繫。
• 開源許可協議：既然是一個開源項目，那麼開源許可協議必然是不可少的，你的開源許但是 MIT、BSD 仍是 ISC、Apache？固然你也須要了解這些開源許可的意義，這裏推薦一篇知乎問答。

1.2 CONTRIBUTING

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

1.3 LICENSE

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

2. 代碼風格

關於代碼風格，每一個人可能都會有本身的偏好，這些偏好中有好的，也有壞的，一些很差的代碼風格會讓其餘開發者感到不快，減小了你們對於代碼的關注，好在強大的開源社區中一樣也有人開源了代碼風格規範，這些代碼規範都通過了激烈的討論和充分的修改，爲大多數人所承認，須要注意的是代碼風格並不僅是縮進、空格這一類的事情，它更多地是一種代碼習慣，好比什麼時候使用 const，什麼時候使用 let，是否有聲明但未使用的變量等等，這些習慣並不影響代碼的功能，卻能夠很大程度上決定代碼的可維護性、易讀性和下降犯錯的機會，同時也讓其餘開發者對你的項目另眼相看。

2.1 代碼風格推薦

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 年推出之後已經有不少谷歌的項目遵循這份規範進行編碼，喜歡谷歌風格的朋友可使用。

2.2 LINT

看到這裏有人會有疑問，規範雖然好，但是條目太多了，我雖然能夠學習，可是全都記住難度過高了。不用擔憂，你的痛點也是你們的痛點，早已經有工具幫助咱們來解決這一問題，並且更棒的是他能夠無縫地與你的 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/ ，這裏有更詳細的講解，你還能夠直接搜索對應的規則。

3. 測試

靠人工來保證項目的維護老是不出差錯是不靠譜的，人總有健忘和糊塗的時候，尤爲是當項目愈來愈複雜時，一我的甚至可能沒法所有了解項目的所有邏輯，這時咱們就要依靠測試來保證項目的可靠性，這裏的測試包括但不限於，單元功能測試，UI 測試，兼容性測試等等。

3.1 測試體系

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

• 測試運行器(Test runner)：主要負責測試的自動化，主要負責調用測試框架和測試代碼，自動打開瀏覽器或者 js 環境，執行測試。
• 測試框架(Testing Framework)：測試框架規定了測試風格和測試的生命週期(lifeCircle hook)。
• 斷言庫(Assertion library)：每一個測試單元是經過一句或者一組斷言來組成的，每一句斷言聲明瞭對一種功能的描述。例如 expect(window.r).to.be(undefined);。

3.2 Test runner

一個優秀的 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

固然這只是最初始化的配置，咱們尚未寫真正的測試，因此這裏只是一個空架子。

3.3 測試框架

測試框架有不少:

• 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 的官方文檔。

3.4 斷言庫

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

• 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()

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

4. 持續集成

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

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

接入到 github 的全部 CI 能夠在 https://github.com/integrations 中查看。

4.1 CI: Travis CI/ CircleCI

二者都是接入 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

4.2 跨瀏覽器集成測試：SAUCELABS & Browser Stack

這兩個工具都是提供了多種瀏覽器環境，包括 pc 端和移動端，而後在多種環境下都是去運行測試腳本，來測試項目的瀏覽器兼容性。其中 SAUCELABS 對於開源項目徹底免費，只須要走他的 Open Source Plan 便可，而 Browser Stack 雖然也提供了 Open Source 的免費計劃，但比較麻煩，須要郵件聯繫，而且在項目 README 中提到其對項目的支持。手動配置這些集成仍是比較麻煩的，通常咱們都藉助 karma 來集成，使用 karma 的 karma-saucelabs-launcher 和 karma-browserstack-launcher。

saucelabs 也提供了很棒的 badge

4.3 代碼覆蓋率集成 Coveralls

代碼覆蓋率能夠在本地測試裏集成，一樣也能夠在 CI 中集成，經過引入 Coveralls，他能夠將你持續集成測試中獲得的代碼覆蓋率結果作一個記錄和保存，同時及時的反饋給用戶。

Coveralls 也有兩個地方能夠體現：

• 一個是 Coveralls 提供的 badge：

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

圖4：coveralls 的自動 comment

5. 總結

礙於篇幅有限和行文的目的，文中提供的不少點，只是舉了一些例子，點到爲止，同時提供了連接，供你們往後仔細研究。做者但願經過此文，讓讀者瞭解到一個靠譜的前端開源項目應該具有的東西，這個靠譜不只是爲了讓用戶用的放心，更是爲了開發者在開發時心中有譜。那具有了這些就表明了一個成功的開源項目嗎？很遺憾，這只是通往成功的必備條件，一個成功的開源項目還須要開發者更多的經營，最重要的，是一份爲用戶解決痛點的初衷和鍥而不捨的決心。

最後

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

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