Florian Munz, Co-Founder at Depfu

Why do we like repo badges? You know, these:

I think, fundamentally, it’s two things:

  • Surface information about this project that is otherwise a bit hidden
  • Show that we care about something

In the wake of the Gemnasium shutdown announcement a few of our users asked us to offer badges showing the state of dependencies of their repos. I wasn’t really excited about it and realized I was never a big fan of the dependencies badge, because it always looks like this:

I’m sure a lot of work went on in the Gemnasium back-end, tracking versions and comparing them to basically always show you: Guess what? You’re out of date.

I don’t believe we need badges that make maintainers feel guilty about their project, about not spending enough time on it. There is enough of that already.

And let’s face it, updating dependencies is important, but not as important as having your build passing. And more importantly it’s not as binary as a green or a red build. As a user of an open source library, I care that they update dependencies regularly and keep an eye out for security vulnerabilities. I want them to be considerate when adding more dependencies. And I want the library to support a wide range of versions, so it works in my app without any problems.

What we should aim for then is to be “reasonably up-to-date”. To not fall too far behind because then it gets harder and harder to get up-to-date again. And it’s less likely to work in today’s ecosystem.

We need a dependencies badge that is less binary and more intentional and considerate.

Reasonably up-to-date

It’s in the nature of how badges work for them to be quite binary in what they display: The build is passing or not. There are different ways around that, mostly involving a metric: Either a universal one like code coverage, or an opinionated one like the grades and scores Code Climate gives out.

I didn’t like making up a score about the health of your dependency graph. I actually think there could be value in that, as you can incorporate a lot more factors. But it works against my first point of why we like badges in the first place: To surface information. If I have to click through somewhere to understand the score, it’s not as good as getting that information from the badge directly.

But how can we put that notion of “reasonably up-to-date” into a badge?

First we need a few new words to indicate the range and also to differentiate against the existing “up-to-date”/”outdated” usage.

Secondly, we have to come up with a rule for what’s “reasonable up-to-date”. This is admittedly opinionated and not objective. But I’m convinced it’s not actually very controversial.

Latest, Recent, Stale, Insecure

This is my proposal for a new dependencies badge:

Latest:
It’s a very nice feeling to be completely up-to-date and to reward that, there should still be a badge for that. Every dependency is at its latest version.
Recent:
If you’re behind a little bit, your dependencies are “recent”. This is perfectly fine, so the color still shows green. Recent means a certain percentage of your dependencies is behind. Being outdated by a patch, minor or major version gets counted differently.
Stale:
The majority of your dependencies is outdated, often by major versions. This means dependencies haven’t been updated in quite a while. It could still be fine depending on your use case.
Insecure:
The only case the badge is red is if there’s a known security vulnerability. There is really no excuse to not update and if it’s not done there is a very high likelihood this project is actually abandoned.

I think this gives you more realistic information about the state of a project’s dependencies, while not complicating it too much and keeping the simple badge format. It’s intentionally similar to the existing badges, while the new words acknowledge a more complex world than “up-to-date”/”outdated”.

Try it for yourself

We’ve built a simple preview tool where you can quickly paste your gemspec or Gemfile.lock to see how the badge looks for your project:

If it doesn’t seem right, you disagree with this proposal or have more ideas, let us know in this GitHub issue.

And if you want to display this badge and get optional automated dependency updates as well, sign up for Depfu, it’s completely free for public repos.