Matthew Bellantoni

On Versioning Things

Here are a couple mechanisms that I use to version things.  When I say "things," I basically mean software and documents.

Versioning Software Components

When I version software components I use Semantic Versioning.  Hopefully you've heard of this and if you haven't, you should go read it right now. Semantic Versioning, also known as "SemVer," lays out what the major, minor and patch version numbers mean in an x.y.z style version number.

As the name implies, this is the go-to choice when you need to give a version not only a unique identifier, but an identifier which contains a lot of semantic data about its relation to other versions of the thing in question.

(A side note: If you use SemVer, when you release your first version, please bite the bullet and start with version 1.0.0.  Resist the temptation to start at 0.0.1 unless you've got a really good reason to do so.  Nine times out of ten you don't!)

Versioning Documents

When versioning documents, I don't need a versioning mechanism with (much) semantic meaning.  So, I use a simpler convention.

I also stared doing this because I would find that people would always try to infer meaning from an x.y.z style version number--even in the absence of a formal definition of the digits.  And anyway, in cases like these I just need a convention which clearly identifies the uniqueness and ordering of versions.

Many years ago I adopted the convention of using revision letters in this situation.  I think I saw this being used on hardware documentation early in my career.  The full convention I uses is "Rev A," followed by "Rev B" and so on.  I usually don't get past "C."  Pretty self-explanatory!

Examples of this would include something like "Hiring Plan 2H2013 -- Rev A" or "Budget -- Rev C."

I hope you found that useful!