The life and times of Zack Weinberg.
Thursday, 20 June 2002
# 5: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
- 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
- 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.