Ex Bibliotheca

The life and times of Zack Weinberg.

Thursday, 20 June 2002

# 9:45 PM

a rant about version numbers

Version numbers, as you know, Bob, are those odd digit strings attached to computer software. They look like "1.2.4" or "3.1.0". Now, lots of people are out there releasing software without the slightest understanding of how to generate these numbers, so here is my own explanation, after the style of another such (which neglects to say anything about the its/it's mess, but never mind).

This is how to do version numbering right:

Realize that these numbers are not decimal fractions. They are integers separated by periods. That means version 1.99 is older than version 1.100, and version 1.100 is not the same thing as version 1.1.
Only offically released versions of the program get version numbers. Development snapshots don't. Nor do test releases.
A version number should have three components: 1.2.0 or 1.2.3. If the last component is zero, it may be omitted, but that's just shorthand: 1.2 and 1.2.0 are the same thing.
Each of the three components has a meaning:
- The first is the major version. You increment this number only when you have made changes that break backward compatibility. This is to be avoided if at all possible.
- The second is the minor version. You increment this number when you release the result of a development cycle, having made lots of improvements, probably introducing new bugs as well.
- The third is the patch level. You increment this number when you release the result of a bug-fixing cycle. A patch release should have strictly fewer bugs than the previous one, and no additional features.
The first official release of your program is 1.0 (aka 1.0.0).

Now, some of the numerous ways to do it wrong:

Bumping the major version number for no good reason. This is extremely common. If you bump the major version, it means that upgrading is dangerous, because changes were introduced which deliberately broke some of the ways the program used to be used. Do not bump the major version if this is not true.
Not having a three-component version number. If you have fewer than three components, you hide information that your users need. If you have more, you merely create confusion. (Four- and five- component version numbers can be correctly used by repackagers; see for instance the Debian policy manual. But if you wrote the program, use three components.)
Using anything other than numbers in version numbers. Versions such as 1.0a are ambiguous; is that the same as 1.0.1, or is it an alpha test for 1.0 (which shouldn't have had a version number in the first place)? Automatic sorting procedures disagree on how this is supposed to work, as do humans.
Giving version numbers to development snapshots. The worst offender here is the Linux kernel, which makes a distinction between odd and even minor versions, then tacks a ton of extra suffixes on the end because the patchlevel isn't sufficient detail. This is a symptom of that development effort's longstanding habit of not using a proper version control system, but that's beside the point.
Using major version number zero. This is not a total proscription; it is possible to use it correctly, if you know what you are doing. (See Subversion for an example of the correct use of major version zero.) Normally, however, anything before 1.0 is a development snapshot, which — once again — should not have a version number at all.
Distinguishing version X.Y from version X.Y.0. This just plain causes confusion. (Fortunately, very few people do it.)
The GNU maintainer advice for test releases has an especially pernicious suggestion, to use 4.5.90, 4.5.91, ... for test releases up to 4.6; not only does this clash with the namespace of patchlevel releases (what if there really were 90 patchlevels to 4.5?) but it continues by suggesting that the sequel to 4.5.99, if you're not done, should be 4.5.990, which is just plain wrong. See above about version numbers not being decimal fractions. Taking this advice is a common error.

The proper thing to do with development snapshots, by the way, is to give them date stamps, which look like 20020602. It is also acceptable to use 2002-06-02, if you're consistent. No other date format is acceptable; there are far too many of them, they're ambiguous both to humans and computers, and they don't sort right by naïve string comparison. If you are generating snapshots for two different branches at once — say, the main trunk and the 3.1 release branch — you can disambiguate them by mentioning the major and minor number of the previous release on that branch in the bundle name.

Ex Bibliotheca hopes that this has been an informative and useful rant, and that more of you out there will get it right in the future, dammit.

# 1:55 AM

Leonard nitpicks Star Wars: Episode II. And behold, it is funny. Contains the beautiful phrases "...look on the bright side: you wouldn't all be crushed under the jackbooted heel of the Dark Lord of the Sith!" and "I don't know how this could possibly happen, but I could probably think something up if George Lucas put me on the payroll."

(Me, I plan to wait until it comes out on DVD and then propose that the ICSI movie club either MST3K it, or take Dave Trowbridge's advice.)

# 1:35 AM

Hobo Nickels. Check it out. (From Boing Boing.)