Programming

Services and badges: increase your project's visibility and popularity

July 6, 2015
--
User avatar
Adrian Perez
@blackxored

It's interesting that something as small as a badge is a good indicator of your project's health, popularity and status; somewhat essential to improve visibility, and trust, no matter whether your project is open source or private, or is hosted on GitHub, BitBucket, GitLab, or a custom setup. It allows you (and your team) to have a place where you can instantly be aware of your project's status, as well as your users (whether is the general public or management) to have small but interesting metrics on your project.

As a general statement, at the core of this post is, that if you get more users to trust your project, it will get more users, period. We (and I'm wearing the user's hat now, maybe the geek user, granted) want to know if you care about your project at all, if it's well maintained, if it's popular, if you took best practices into account while building it, if it's easy to contribute to, or if they're many of those, the list goes on and on.

While creating this post I stumbled upon Shields.IO, a completely free badges-as-a-service website and I used it as reference to check which ones I've been missing that I might care about. Turns out I was falling short, and they're a few ones that I might consider adding to every new open source project, such as gem downloads and the like (technically speaking, to my open source project templates and generators, but still). Not only it provides a ton of services, it also offers scalable versions (SVG) which (for this website at least and showcasing them) are absolutely great.

Of course, these badges are provided by services, and this post isn't only about badges. By definition also these services would be essential for our goal, and I will be mentioning them along when it makes sense, please notice that most of them are free for open source projects, but will set you back a few bucks for private ones.

To start things off, let's take a look at how an open source project of mine looked like at some point:

Badges wisper-mongoid

And to be honest, while I'm about to add a few throughout this service, or even directly, I think the list I had is the absolute essentials, so let's start by providing some examples and elaborating on those. Please notice that the badges below belong to actual projects and are only used as an example.

The essentials

The version

Version badge

I'm a polyglot developer, but it's no secret that most of the work I do it's done in Ruby. The gem version badge that comes from Rubygems is obviously essential if your project is a gem, it allows users to quickly now what's the latest released version of your gem.

This is essential, and for any open source project, independent of the language, you should search and add the equivalent to your project, whether is NPM, PyPI, CPAN, you name it.

The build

Build

This is another essential that requires no explanation, users would want to know the status of the project and whether is safe to be using their edgy branch or not. Most of them won't, and your branching policy might influence the status of this (I prefer an always passing master branch, in a git-flow workflow); but it's no surprise that this is a strong indicator of your project's health.

Most of the time, I'm using TravisCI, although I also swear for CircleCI, used Jenkins and I've been hearing good things about Semaphore, you can't go wrong with either, if you don't have your pick already.

The coverage

Coverage

Most of this section relates to the previous one, a strong test coverage it's not a sole indicator of your project's quality, but it adds to it. This should be also language-agnostic.

I normally use Coveralls, which uses SimpleCov under the hood. CodeClimate also has it's own coverage section, as most Continuous Integration systems do. You can also take a look at CodeCov.

The dependencies

Not only you need to track your project, but your dependencies make a significant role in its health, a security vulnerability in a major component used by your library or app, in most cases will result in your project being vulnerable, outdated dependencies are a burden to maintain and for your project to evolve.

Gemnasium is a service that will inform you of both in the Ruby ecosystem, and there's David for NodeJS, Requires.IO for Python, etc.

The quality (or some of it)

I love metrics, and CodeClimate is one of my preferred tools for measuring code quality, and a badge is mandatory if you're using it.

Some handy extras

Now that I've described what I consider to be the essentials for every project, let's take a look at the fancy (or optional) ones. For convenience, you can find all of these in the service I described at the introduction of this post, since I'm lazy to link to all of them individually 😂.

The downloads

I think you should only include this if your project is open source, but in any case, it's an easy measure of your project's popularity.

The license

It might be handy to feature your project's license in such a way that users don't have to take extra effort in figuring out whether (and under which conditions) they might be able to modify your work or derive from it.

The Github status

If your project is hosted on GitHub, and you care about the social aspect of coding at all, they're a few project status/branching badges that you can include:

The tipping

If you want people to be able to support the work you're doing in open source, GratiPay (formerly GitTip) is the way to go.

BountySource, as its name implies, it's an open source bounty site, where users can pledge bounties for specific tasks across projects.

Conclusion

Use them with care, as people always say. Sure, we already know what our goal is, and all of them seem useful, but the experience would be detrimental for a user trying to get to your README's first line and having to scan over two rows of badges, with power comes responsibility...

That concludes this post's round-up, I hope I can approach every open source or private project from now on and I discover at least the essential badges and services being used on them, it would be a great experience for sure, I also hope you add them to your own projects, and even include some of the extras. You're free to suggest one if I missed it in the comments below, or join the discussion on Reddit.

~ EOF ~

Craftmanship Journey
λ
Software Engineering Blog

Stay in Touch


© 2018 Adrian Perez