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:
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 :-)