Antti-Juhani Kaijanaho: Version Numbering Rant
Inspired by some, I decided to impose my opinion about software version numbering on everybody.
Rule 1: Version numbers are an ordering property
The chief reason for having version numbers is to distinguish between releases.
A few definitions:
- Configuration
- A bundle of particular versions of files that comprise the software in question, including documentation and data files (not including input, of course) that it requires. (Note that this is a different meaning from what we are user to in the free software world. It, however, is standard terminology in software engineering.)
- Release
- A particular configuration published with the intent that the users (or a particular subgroup of users) get it and use it.
Since usually people want only the newest release, it is useful to mark the newest release. The version number is an excellent tool for this: as long as a number bigger than any previously assigned for the same product is assigned to each new release, anybody can determine, which of several releases is newest.
It is therefore imperative that the version number suggests an ordering. That is a problem: there are two popular version number schemes:- The version number can be a decimal number: 3.2 > 3.14
- The version number can be a sequence of integers: 3.2 > 3.14
If you use a simple integer and always choose a larger number than you've previously chosen, there is little chance of mistakes. Choosing them sequentially is best, but if you want, there is little harm in skipping a few, for example from 6 to 2004 :)
Rule 2: Version numbers carry no semantics
A popular mistake is encoding some semantics in version numbers. Usually, some vague indication of "readiness" is indicated, by for example using a zero-dot version number (e.g. 0.54) or by going from 2.09 to 2.89 in one step. The problem is that the intended semantics usually is not obvious to someone who is not intimately familiar with your program (unless you put a great deal of energy into teaching people about your idiosyncracies).
It is particularly bad to encode the status of a release (such as the property of being a release candidate) in the version number. Your last release candidate should be your first release! If you reconstruct the release to fix the version number, you may break it. Instead, indicate the release candidateness by prominent warnings at download sites and by putting them in a distinctive place.
There is one exception to the rule: if your semantics is clear and not knowing it will not hurt the user, then it is OK.
Rule 3: Only use dots to indicate major/minor/patchlevel separations
Do not label your program 1.0 just because everybody else does. If you go for the dotted version number, you will immediately have the problem of which scheme to use (decimal or integer-sequence, discussed above), although in some communities you can forget that problem because there is a community-wide standard (e.g. in Debian, integer-sequence is the way to go). The bigger problem, however, is that you are encoding semantics in your version number, and more often than not, you don't know what you want to say with it.
There is one fairly universally understood dotted schema: that of a major number, a minor number and possibly a patchlevel. However, if you choose this schema, be clear of its semantics:- The first integer (the X of X.Y.Z) is the major version number. Change in the major number indicates a significant change that is expected to break existing installations.
- The second integer (the Y of X.Y.Z) is the minor version number. Change in the minor number while the major number stays the same indicates a change that introduces noteworthy new features. Breakage of existing installations is not expected.
- The third integer (the Z of X.Y.Z) is the patchlevel, and it may be missing. Change of the patchlevel while the minor and major numbers stay unchanged indicates a change that does not introduce anything new but fixes bugs in existing featutres. Patchlevel releases are extremely unlikely to cause breakage in existing installations.
If you go for this option, make sure you understand its semantics and design your release engineering practices accordingly. Do not change the major number just on a whim; use it to signal an upgrade that requires special attention from users or administrators. Likewise, keep the minor number constant if you do not introduce any new features. If you do a patchlevel release, make sure, triple checking everything, that the release is a harmless upgrade.
There is a version of this schema where only two integers are used. Its semantics is not as clear, as there are two possible interpretations:- There is no major version number. In this case, it is expected that no "break a few eggs" releases will be ever needed.
- There is no patchlevel number. In this case, all releases are expected to bring new features. A patchlevel can be introduced as needed, for example when a maintenance branch is created while development continues in the mainline.
2004-06-29T00:57+0300 - /en/programming
Trackback url: http://antti-juhani.kaijanaho.info/blog/en/programming/version-numbering.trackback (trackback on rikki / trackback is broken)
Your Comment