一个靠谱的前端开源项目须要什么？

2019年8月30日 247次阅读 来源: 红白

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 为例来给人人一个也许的印象。

起首装置 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 断言库

断言库也有许多的挑选，个中比较有名气的有：

个中，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，转载请保存作者信息。

    原文作者：红白
    原文地址: https://segmentfault.com/a/1190000005859766
    本文转自网络文章，转载此文章仅为分享知识，如有侵权，请联系博主进行删除。
点赞