Project status badges
Written on 17 Dec 2016
Most code that I write outside of work ends up on the internet sooner or later, but not all code that I put on the internet is of equal quality. Some of it is quite nice and polished. Other code is a quick hack or some experiment; it may still be useful for others – and why not put it on the web – but it’s probably a good idea to set some expectations about the status.
I’m hardly the first person to do this. A ‘beta’ label or ‘pre-1.0’ version are commonly used, but also commonly abused. So commonly abused that a ‘beta’ label or ‘0.1’ release is pretty useless these days for meaningful communication about a project’s status.
To set some expectations, I’ve been adding text to the top of my README files. This works, but is a bit ugly. Today I made some ‘shields’ to make it look a bit better. I’ve also written brief explainer pages for every status.
Here they are:
May work, or may sacrifice your first-born to Justin Bieber.
Should work for most purposes; is reasonably bug-free and documented.
Does what it needs to do and there are no known bugs; don’t expect any large changes or feature additions.
The author has stopped working on it, but should still work and may still be useful.
And the Markdown:
I didn’t create any of the images myself. It’s the shields.io service. If you want, you can modify the colours by frobbing with the URL.
Some might argue there should be more statuses, but I like to keep things simple.
If your project is unmaintained and no longer works you should probably take it offline. Broken code serves no one.
If your code isn’t Experimental but not ‘reasonably bug-free and documented’ then it is, in fact, Experimental.
No one would consider a washing machine with a long list of defects or no instructions on how to use acceptable. Why should we for software? I don’t think that creating an in-between ‘yeah, it sort of works’ status will help anyone.
Just go and fix those few bugs and/or write some docs :-)