On Version Numbers

I have been thinking about using version numbers lately while working on some API extension of the Sling Engine bundle. So here is what I think versions are all about and that we all should be very careful when changing code and assigning versions to it.

On high-level versions have various aspects:
Syntax: There is no global agreement on the correct syntax of versions. I tend to like the OSGi syntax specification: The version has four parts separated by dots. The first three parts are numbers, called the major, minor and micro version. The fourth part is a plain (reduced character set) string which may be used to describe a particular version. Version numbers are compared as you would expect, except that the fourth part is employed case-sensitive string comparison comparing the actual Unicode codepoints of the characters.

Semantic: The semantics of a version define what it means to increment each place of a version. In the world of software development, there is even less agreement on the semantics of version numbers than there is agreement on the syntax. The OSGi specification just defines suggested semantics.

Expectations: When seeing product version numbers people tend to have expectations towards the products. For example, when Firefox went from 2.x to 3.0 we expected a major change. Likewise when Day upgraded the version number to 5 for the newest version of Communiqué the expectation is correct, that it is a major new version of the product. In fact, we completely rewrote Communiqué for the 5.0 release. 

Version items: When it comes to applying version numbers to things there are quite a number of things in a single product, which may be numbered. Take for example Day Communiqué 5. There is a product - the thing you take out of the box and install on your server. Then there are OSGi bundles. Finally, there are Java packages shared between the bundles and used by the application scripts. 

So here are my definitions of the version number aspects laid out above.

Syntax: IMHO the Syntax for version numbers as defined in the OSGi Core specification (Section 3.2.4, Version) is good enough and clear for most uses. The nice thing about this specification is that in Section 3.2.5, Version Ranges, a syntax is defined to define ranges of versions. Such ranges are of great use when depending on other items. Most importantly, of course, this would be a list of imported Java packages.

Semantics: As for the semantics the main problem comes from the fact, that not all versioned items understand version numbers in the same way. For example on a product level, c.f. Day Communiqué, the version number of a release is generally defined by marketing and/or product management.

I will not dive into how product numbers are to be defined. This is outside of my working knowledge and beyond my abilities.

On the OSGi bundle level on the other hand and even more so on the Java package level (for OSGi package exports), the version number is more a call of the developer. Version numbers on this level are intended to convey to other developers something about the evolution of the bundle and/or package.

Let's start with exported Java packages. I tend to attribute the following semantics to the parts of a version number:

• Increasing the major version number means the API has been modified in an incompatible way. Mostly this means public classes, interfaces, methods, fields have been removed or renamed. As a consequence code using and implementing the API will break and has to be modified.
• Increasing the minor version number means the API has just been enhanced in a way that is compatible with use. Increasing the minor version number, though, means that code implementing the API might have to be modified to comply with the added API like the definition of new methods.
• Increasing the micro version number means that there have been some bug fixes. Generally, a pure API consisting of just interfaces has little chance for bugs which do not amount to minor or even major version number increase. If the exported packages of a bundle happen to contain concrete or abstract classes with implementation code, bugs cannot be excluded. As such it is conceivable that a micro version number of an exported package might be increased.
• As for the qualifier part, as the fourth part of a version number is called by the OSGi specification, this meaning of this part is completely free. On a package export level, I would go as far as to say, it should not generally be used. The qualifier part may be interesting on an OSGi bundle level to create inter-release builds.

Expectations People's expectations as it comes to version numbers is not easy to convey. Most people expect different things. But I think one thing is common to all: If there is a version number increase something must have changed.

So, I think to use developers it is important to understand, that we only increase the version number of an item if there is a change -- not sure whether a fixed spelling error in some Java comment changes enough. Again, your mileage may vary if you happen to be a product manager for a product to be sold.

Recommendations 

Based on how I understand the version number parts in terms of exported packages, here are my recommendations for package imports and bundle versions.

• If you implement the exported API of another bundle, import the API package using a version range of the form [x.y,x.y+1). This means accept any increment in the micro and qualifier parts. But as soon as the minor version number changes, consider this an incompatibility.
• If you use an exported API, import the API package using a version range of the form [x.y,x+1). This means accept any version starting with a minimum number up to the next breaking API change identified by a new major version number.
• Don't increase the version number of an API package if nothing in that package has changed at all.
• Bundles should be versions following versioning of exported packages. So if at least one of the exported packages has a major version number increase, the bundle's version should also have a major version number increase. Likewise for the minor number. The use of qualifiers is optional and sometimes helpful.
• Apart from being driven by versioning of exported packages, bundle versions may also be increased depending on the extent of changes in the bundle. For example in the case of a pure implementation bundle, greatly increasing the functionality might give rise to a major version number increase of the bundle.
• If you are using Maven to build your projects, always depend on the lowest version of a dependent module which has the API functions you need.

Link The Eclipse site contains a very interesting and IMHO very reality proven text about versioning of products, bundles, and packages: Version Numbering

Update 2012/10/11 The OSGi Alliance released an excellent white paper on Semantic Versioning which pretty much aligns with what I was talking about above.