I’ve been pondering version numbers a lot recently – there’s a lot of new “libraries” and major upgrades going on at work, and I’ve seen a few examples “in the wild” lately of people having to choose version numbers – and not always getting it right. It may seem like it’s “just a label”, but give something the “wrong” version number, and you can cause a lot of unnecessary confusion, as people will make assumptions based on it.

By an interesting coincidence, just as I was thinking about this post, I came upon Tom Preston-Warner’s “Semantic Versioning Specification”, which covers some of the issues nicely. But while he is mainly considering the problems of “dependency hell” – very important to consider when writing a library or tool which is likely to become a dependency for some other project downstream – there are wider issues with what a version number means to people, even if you are making a desktop application for use by “ordinary folks”.

So, here are my “Golden Rules of Version Naming” – as with everything in life, they are often mutually contradictory, and full of exceptions; life is all about compromise, but that doesn’t mean you have to compromise everything.

Be Consistent

Be Consistent About Progression

The most obvious thing that a version number should show is an obvious and consistent progression – the numbers should be getting higher, in some meaningful way. This may sound so obvious as not to mention, but it’s possible to get it wrong – consider:

• The current version of pgAdmin – the popular open source desktop admin tool for PostgreSQL databases – is pgAdmin III 1.10.1. Now, I don’t know the history of the project, but presumably at some point “pgAdmin 3” was started as a major rewrite of “pgAdmin 2”; but why not simply start it at version 3.0? The only reason I can think of is that they wanted to have “0.x” releases of the new codebase; but this is hardly an unsolved problem – Firefox 3.0 had 8 Alpha and 5 Beta releases without needing to reset to 1.0 afterwards…
• The incredibly popular Street Fighter 2 was infamous throughout the ’90s for increasingly hyperbolic “edition” names, such as “Super Street Fighter II Turbo”. To be fair, it seems a Street Fighter 3 was finally released in 1997, although that too received 3 “editions”.
• An interesting problem comes up if your versions aren’t just numbers. Ubuntu releases have both a version “number” which is actually an abbreviated year and month, and an alliterative animal code-name (such as “Dapper Drake” for version 6.06). Cunningly, these code-names are now being assigned in alphabetical order, so you can tell at a glance that an “Intrepid Ibex” is more out of date than a “Karmic Koala”.

Be Consistent in Your Logic

It’s also important to be consistent with your own versioning scheme – you could adopt “Semantic Versioning”, or something like it; or perhaps you could adopt the convention used by Linux, GNOME, and others that “every odd minor release is unstable” (so Linux 2.4.x was stable, and once 2.5.x became stable, it was renamed 2.6.x), but either way, you need to decide early on, and stick to it.

• A recent failure of this is Lightning, the popular calendar plugin for Thunderbird. Having released versions numbered from 0.1 to 0.9, they released something called “1.0 beta 1”, the first release compatible with Thunderbird 3. This led to plenty of users – myself included – waiting patiently for version 1.0, which was presumably just around the corner. Wrong – the developers clarified the situation with a blog post proclaiming this “the best Lightning release … released to the public”. Evidently, they considered 0.9 to also be a “beta” release, but in that case surely this is not “beta 1” but “beta 10”?
• Sometimes, of course, you define your convention wrong, and have to change it; Firefox 2.0.x.x had a very strict four-part versioning scheme. However, in practice, the highest release in that series was 2.0.0.20; so they waited until version 3, and revised it to have just three parts, as in version 3.5.8.

Be Consistent Across Related Products

If you have a series of closely related products, or products which you sell as a bundle, it’s a good idea to give them consistent version names.

• The prime example of this is probably Microsoft Office, which originally bundled together separate versions of Word and Excel. As the suite began to gain more common functionality, branding, and additional tools, Microsoft decided to give every program in the suite the same version, starting with 7.0 for Office 95 – even though only Word had reached 6.0, itself skipping versions 3, 4, and 5 on Windows as they had been used for separate Mac releases.
• An interesting case it TortoiseSVN, which is built against the strictly-versioned Subversion libraries. Most (but not all) fixes to underlying Subversion code require a new version or Tortoise, but there are also bug and even functionality improvements to the interface itself. The solution they’ve chosen is to track the first two parts of the Subversion version, but track there own releases with the third part – so the latest version is 1.6.7, built against Subversion 1.6.9.
• The author of the Lightning Provider for Google Calendar extension fell foul of this consistency when updating to support the badly named “1.0 beta 1” release mentioned above – the extension had only reached version 0.6, but he duly added “beta 1” to the name, explaining thus:
  

  “Even though the version number suggests this is beta level software, it has been tested just as well as the previous releases. The naming is aligned to the Lightning version numbers.”

• Although careful with their over-all logic, the Mozilla project has a rather odd inconsistency between the internal branch versions of the “Gecko” core and the applications built from it. Namely, Firefox 3.6 is Gecko 1.9.2, while Thunderbird 3.0 is Gecko 1.9.1 (as was Firefox 3.5); these apparently follow a very slow progression from the versions of the original Mozilla suite, which ceased at version 1.7.13 three years ago.

Be Consistent With Your Branding

The naming scheme that makes sense for programmers may not make for great branding, and vice versa; but that’s no reason not to at least attempt to keep version-like branding consistent with your actual versioning.

• Probably the most famous failure of this recently has been Windows 7 – not only does no-one know why it got that name, but its internal (kernel) version number is actually 6.1 – if you want to concoct your own theory, you can consult my handy table of Windows versions. At some point, a version of Windows will presumably be released with an internal version number of 7.0, leading to the fun of distinguishing “Windows 7” from “Windows version 7.0”. I guess if they have any sense, the developers can skip the internal version to 8.0…
• On the other hand, MacOS X, despite being an almost entirely different system from MacOS 9 and earlier, has had subsequent releases numbered as 10.1, 10.2, and so on, so that the “X for 10” branding is still valid.
• Sun’s branding around Java is (or has been) a total minefield; my favourite example is a paragraph from Computer Weekly magazine, which I unfortunately no longer have, but went something along the lines of “at the upcoming JavaOne ’03 conference, Sun will launch the Java2 J2SE JRE 1.4, along with Sun One Studio 5 and Sun One Application Server 7” (versions based on this article, which is almost as bad). If “Java 2” was so much better than “Java 1”, why did none of the tools receive a major version increment!?

Be Bold

Be Bold With Numbers Above 9

A common problem with version numbers is that they look like decimal numbers – version 0.2 looks like something you can do maths with, and version 0.2.0 could just be “0.2 with a .0 stuck on”. This leads programmers to the quite erroneous assumption that unless they started with 0.01, they will run out of digits at 0.9 – there is nothing wrong with version 0.10.

One way to look at this is that version strings are numbers, but not in base 10 but some arbitrarily high base; the dots aren’t decimal points, they’re to separate the “digits”, each of which is written in base 10 to keep the alphabet small. Or just say “it’s not a number” and get on with it.

The only problem comes when trying to sort lists, such as files in a directory, but that’s because string sorting algorithms are generally pretty awful at sorting numbers anyway – this is not a bug in your naming convention, it’s a bug in your file manager.

• This is probably what caused the mess with Lightning mentioned earlier – having reached version 0.9, but not ready for the big 1.0, the developers panicked, and picked a confusing fudge. If they’d stuck to 0.10, they could have carried on with 0.11 if necessary, and no-one would be in any doubt what they meant.
• Another great example is Flyspray, a bug tracking system which branched for 1.0, then seemed to approach it asymptotically with increasingly daft version numbers, including 0.9.9.5.1! Sadly, the project seems to have stalled, and I suspect it’s unlikely 1.0 will ever be released.

Be Bold With Major Versions

The other thing developers are always reluctant to do is increase the “major” version number. Projects will continue for years on versions in a 1.x – or even 0.x – sequence, because the new version is somehow never “quite different enough”. Indeed, given a three- or four-part versioning scheme, people will try to mark as little change as possible – version 1.1 happens far more often than version 2.0, but the actual change varies wildly.

This, in part, is what the “Semantic Versioning Specification” is trying to solve (he even covers the 1.0 problem in the FAQ). But in general don’t be afraid of version 1.0, or 2.0; and every now and then, when planning the next release, ask yourself “why not bump the major version?”

• One of our main projects at work for a long time had 2 main branches, numbered 2.3.x and 2.5.x. Eventually, someone decided it was time to call it 2.6, but we continued to have releases like 2.6.2.5 until we could reset the scheme (like Firefox!) with version 3.0.
• This is, of course, what motivated both Lightning and Flyspray to odd release numbers – they didn’t feel they’d “done enough” for version 1.0
• This is also part of the problem with pgAdmin – how many times can you release 1.0, and update to 1.x, before you have to admit you’ve reached 2.0?
• On the other hand, one project that has recently made a considered decision to bump a major rather than minor version number is PostgreSQL itself – the next release will be not 8.5 but 9.0