如果你常常使用 GitHub,稍微留心就会发现,不少项目都有勋章(badges),那这些勋章有什么用呢?要怎么给自己的项目也「戴上」勋章呢?

Travis Coveralls PyPI License
Travis badge Coveralls badge PyPI Version License

勋章的作用

在继续介绍勋章之前,我们先了解什么是持续集成。

持续集成

有经验的开发者往往对自己写的代码有很强的「信心」,这种「信心」来自于丰富的经验,丰富到对代码的任何一点改动,都能被他们的「大局观」给捕捉到。但是随着代码规模增加,无论开发者的经验如何丰富,也很难继续「掌控」全局。因为开发者对项目其他部分可能一无所知,不知道其他开发者提供的接口是不是足够健壮,不知道对某个文件的修改会不会影响其他函数的调用,所有的这些未知都会让开发者逐渐丧失「信心」。

众所周知,给项目加上充足的测试通常能很好的解决上述问题。不过保持多高的测试频率才适当呢?应当每完成一个模块测试一次,或者每完成一个函数测试一次?一个自然而然的想法是,测试频率越高越好,不过如果项目迭代速度很快,每次都手动测试,等待测试结果出来再继续开发,这个过程就有点繁琐了。因此,有人提出了持续集成1的概念。持续集成的核心想法是:如果有代码更新,运行自动化测试,并给出测试结果。持续集成的直接好处就是:如果有 bug,很快就能发现,并能定位到提交者(commiter),那么 bug 就能在更短的周期内被修复。

如果我们在 GitHub 上的开源项目也能做到持续集成,那么项目的质量就有所保证。也因此,无论是开发者,还是使用者都会对项目更加有信心。那么持续集成的结果怎么表达给项目的使用者呢,总不能叫他们去看冗长的分析结果吧?答案就是—勋章。

持续集成服务

Travis CI Travis badge

Travis CI 是一个免费为开源项目提供持续集成的网站。在与 GitHub 的账号关联以后,只需按一个按钮,写好 .travis.yml,就能让它对每一个 commit 或 pull request 按照 .travis.yml 中的规则执行脚本。

它实现的功能看似简单,但却十分强大,前面提到的自动化测试就是通过它实现的。以 Easy-Karabiner.travis.yml 为例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
language: python
python:
  - "2.7"
  - "3.3"
  - "3.4"
  - "3.5"
install:
  - pip install coveralls
  - pip install lxml click
cache:
  directories:
    - $HOME/.cache/pip
script:
  - python setup.py install
  - nosetests --with-coverage --cover-package=easy_karabiner
after_success:
  - coveralls

上面的规则告诉 Travis CI 在四种 Python 环境下分别进行相同的操作:

  1. 安装依赖:pip install
  2. 安装项目:python setup.py install
  3. 执行测试:nosetests
  4. 上传测试结果到 Coveralls:coveralls

只有所有的操作都执行成功,它才会 passing 。

Coveralls Coveralls badge

Coveralls 是一个提供测试覆盖率分析的网站,它能告诉你每个文件的测试覆盖率是多少,甚至代码中哪些行没有被测试用例覆盖到也能在报告中看到。更棒的是,对开源项目永久免费!

coveralls-example-file.png coveralls-example-detail.png

Coveralls 的使用和 Travis CI 略有不同,其步骤如下(详见 Travis CI 中的示例):

  1. 与 GitHub 帐号关联,Turn on 需要分析的 repo
  2. 在 Travis CI 中执行测试,并生成 Coveralls 支持的测试报告
  3. 执行 coveralls 命令上传测试报告

目前 Coveralls 支持的语言和服务如下:

  • 语言:Ruby、Python、PHP、Node.js、C/C++、Scala
  • CI 服务:Travis CI、Travis Pro、CircleCI、Jenkins、Semaphore、Codeship

如果开发语言是 Python,个人推荐下面这套 Combo:

Landscape Landscape badge

Landscape提供 Python 代码质量分析的网站,它能帮助你发现代码中的错误或「坏味道」,比如:

landscape-example-warning.png landscape-example-error.png

同样,它也能给出每个文件的「健康情况」:

landscape-example-score.png

Landscape 默认使用 pylint 进行分析,也可以创建 .landscape.yml 文件,并在里面配置使用其他工具或者 disable 一些检查,比如:

1
2
3
4
5
pylint:
    disable:
        - unused-argument
        - redefined-builtin
        - arguments-differ

获取勋章

上述持续集成服务自身就有提供勋章,拿 loggerhead/Easy-Karabiner 为例,这些勋章的链接分别是:

如果想添加其他勋章,可以在 http://shields.io/ 找找看,它提供了很多种类的勋章,比如:

  • GitHub: Stars badge Forks badge Issues badge
  • PyPI2: PyPI download badge PyPI version badge PyPI pyversions badge

不过 Shields.io 只给出了勋章的示例链接,具体的格式还得靠自己观察……比如:


  1. 关于持续集成更详细的介绍可以看看这篇博客:持续集成是什么? 

  2. PyPI 是 Python Package Index 的缩写,通过 pip install 命令下载的包都必须先上传到这里,具体的操作过程参见博客:How to submit a package to PyPI