常常在 github、 npm上看到一个个花花绿绿的 badges,这些已经成为了开源项目的标配。
看下Vue
的徽章:
常用徽章
-
是否构建通过,可以通过持续集成工具获取。
Vue使用的是 CircleCI,我用的 Travis CI。
构建过程,可以看下Vue
的配置文件 .circleci/config.yml。大致是:下载依赖 => 代码lint => 测试覆盖率统计 => 端到端测试 => srr-weex测试 => 回归测试 。 -
测试覆盖率统计,数据来源上面的构建过程,将跑完的结果发送到对应平台。
Vue使用的 codecov.io,我用的 coveralls.io 。 -
代码质量分析,通过 codebeat.co 获取。这个是独立的,从复杂度,代码复用等方面进行分析。Vue没有上这个徽章。
一. 徽标简介
GitHub 项目的 README.md 中可以添加徽章(Badge)对项目进行标记和说明,这些好看的小图标不仅简洁美观,而且还包含了清晰易读的信息。
徽标主要由图片和对应的链接(当然,你可以不填)组成,徽标图片的话一般由左半部分的名称和右半部分的值组成。
一枚普通的徽标
GitHub 徽标的官方网站是 http://shields.io/,我萌可以在官网预览绝大部分的徽标样式,然后选择自己喜欢的(当然首先需要适用于自己的目标项目)徽标,添加到自己的项目文档中去。
Shields.IO
徽标并不是添加的越多越好,合理地选择适合项目的徽标做具有针对性地添加才是理性的做法,像EFQRCode这样堆积徽标的无脑行为并不是十分可取,在这里提出这一点,希望大家不要盲目追求数量。
二. 常用徽标添加
常用的徽标主要有持续集成状态、项目版本信息、代码测试覆盖率、项目支持平台、项目语言、代码分析等,下面我萌就来依次添加这些可爱的徽标!
1. 持续集成状态
持续集成的话推荐 Travis CI,针对开源项目免费,所以你的私有项目无法享受到免费的持续构建服务,不过我们的目的貌似就是给开源项目添加徽标。
同类型的产品还有CircleCI,不过目前跑 OS X 项目需要额外付费,免费版提供一个 Linux 项目队列,作为非付费用户在这里不多做评价,大佬们可以自己试下。其他还有诸如 Jenkins
和 Codeship 等,大家可以在 http://shields.io/ 的 Build 这一栏自行翻阅。
接下来就是 Travis CI 的集成工作了,首先打开 https://travis-ci.org/ 注册一个 Travis-CI 账号,可以通过 GitHub 账户直接登陆。
然后参考 官方文档,根据你的项目语言或类型选择具体的配置方式,主要就是在项目中添加一个 .travis.yml 配置文件,告诉 Travis CI 怎样对你的项目进行编译或测试。这里有一个 Swift CocoaPods 库的集成示例,可以参考一下:http://www.jianshu.com/p/beaa9ec9183d。
然后徽标图片地址是这个样子的:
http://img.shields.io/travis/{GitHub 用户名}/{项目名称}.svg
将上面 URL 中的 {GitHub 用户名} 和 {项目名称} 替换为你的即可,再加上该项目在 Travis CI 上的地址,以 Alamofire 为例,最后集成完成的 Markdown 代码和效果大概是这个样子:
[![](https://travis-ci.org/Alamofire/Alamofire.svg?branch=master)](https://travis-ci.org/Alamofire/Alamofire)
当然如果你的编译没跑过或者发生错误之类的,会出现其他的状态,比如酱紫的:
这里需要指出的是,开源项目的 Travis CI 也是公开的,包括日志和历史记录在内,都是针对所有人可见的,所以小伙伴们一定不要把密码、私钥等重要信息暴露了。
2. 项目下载量
项目被下载的次数,这个的话各个平台的统计都是独立的,比如发布在 CocoaPods 的项目下载量徽标图片地址如下,以 AFNetworking 为例:
总下载量:https://img.shields.io/cocoapods/dt/AFNetworking.svg
月下载量:https://img.shields.io/cocoapods/dm/AFNetworking.svg
周下载量:https://img.shields.io/cocoapods/dw/AFNetworking.svg
效果如下:
如果你的库已经发布到 CocoaPods 的话,我们只要把上面的 AFNetworking 改为自己的项目名称即可。更多其他发布方式如 apm、npm、Gem 等可查阅 http://shields.io/ 的 Downloads 一栏。
3. 项目版本信息
这个的话,因为我的 iOS 库是发布在 CocoaPods 的,我用的是 CocoaPods 提供的,URL 如下:
https://img.shields.io/cocoapods/v/{项目名称}.svg?style=flat
以 Alamofire 为例,Markdown 代码和效果如下:
![](https://img.shields.io/cocoapods/v/Alamofire.svg?style=flat)
如果你的库已经发布到 CocoaPods 的话,我们只要把上面的 Alamofire 改为自己的项目名称即可。更多其他发布方式如 apm、npm、Gem 等可查阅 http://shields.io/ 的 Version 一栏。
如果你的发布工具不提供项目版本信息的徽标的话,可以用自定义徽标的方式实现,具体可参考下文自定义徽标一节,这里给出徽标代码:
https://img.shields.io/badge/{发布方式}-{版本号}-519dd9.svg
将 {发布方式} 和 {版本号} 替换为你的项目目前的发布方式和版本号即可,例如通过 360 应用商店发布,发布版本号为 v1.2.3:
![](https://img.shields.io/badge/360_store-v1.2.3-519dd9.svg)
4. 代码测试覆盖率
代码测试覆盖率的话推荐 Codecov。同类产品有 Coveralls,不过网站风格略复古,文档也不详细,安装过程也复杂,需要配置一大堆奇怪的东西,遂不推荐。
同样的,Codecov 可以直接使用 GitHub 账号登陆,需要结合 Travis CI 使用,在 .travis.yml 文件中添加一个回调触发 Codecov 的刷新,同时需要打开工程中的测试覆盖信息收集,XCode 中的设置如下
然后,我们就可以在 Setting 中的 Badge 一栏找到添加图标的代码啦:
最终效果如下:
codecov
5. 项目支持平台
这个的话,因为我的 iOS 库是发布在 CocoaPods 的,我用的是 CocoaPods 提供的,URL 如下:
https://img.shields.io/cocoapods/p/{项目名称}.svg?style=flat
以 Alamofire 为例,Markdown 代码和效果如下:
![](https://img.shields.io/cocoapods/p/Alamofire.svg?style=flat)
如果你的库已经发布到 CocoaPods 的话,我们只要把上面的 Alamofire 改为自己的项目名称即可。如果你的发布工具不提供项目支持平台的徽标的话,可以用自定义徽标的方式实现,具体可参考下文自定义徽标一节,这里给出徽标代码:
https://img.shields.io/badge/platform-{项目支持平台}-lightgrey.svg
将 {项目支持平台} 替换为你的项目目前的版本号即可,例如 ios:
![](https://img.shields.io/badge/platform-ios-lightgrey.svg)
6. 项目语言
嗯,这个完全是用自定义徽标实现的,具体可参考下文自定义徽标一节,这里给出徽标代码:
https://img.shields.io/badge/language-{项目语言}-{背景色}.svg
将 {项目语言} 和 {背景色} 替换为你的项目目前的语言和你想要的背景色即可,这里以 Swift 为例,我们用上 Swift 官方橘色:
![](https://img.shields.io/badge/language-swift-orange.svg)