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 a 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 employs 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 apply 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 layed 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 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 may 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 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 for 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 ammount 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 the 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

Peoples expections as it comes to version numbers is not ease 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 is change enough. Again, your mileage may vary if you happen to be 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 upto the next breaking API chnage 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 functionality 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. 

Kommentare

Kommentar veröffentlichen

Beliebte Posts aus diesem Blog

Ready to serve requests ...

In the Apache Sling project we have an interesting problem : Knowing when the application has finished its startup. Coming from a background of a traditional application, you know when the system has finished its startup. For example, a servlet container knows it has finished the startup, when all web applications have been started. In Apache Sling, the situation is a bit different: Apache Sling is an extensible system, where extensions may simply be added by adding more bundles. "Easy", you say, "just wait for all bundles to have been started and you know when the application is ready". True, but there is a catch. To extend Apache Sling, you register services with the OSGi registry. "Still easy", you might say. Right, if the services are all started by bundle activators, we still can depend on having all bundles started for the system to be ready. Again, this is only part of the story: Some services depend on other services. So the dependent services may
Mehr anzeigen

LinkedHashMap's hidden (?) features

Recently I discovered two very nice features of the java.util.LinkedHashMap : accessOrder and removeEldestEntry(Entry) . These features combined let you implement simple LRU caches in under two minutes. accessOrder The accessOrder flag is set when creating the LinkedHashMap instance using the LinkedHashMap(int initialCapacity, float loadFactor, boolean accessOrder) constructor. This boolean flag specifies how the entries in the map are ordered: accessOrder=true The elements are ordered according to their access: When iterating over the map the most recently accessed entry is returned first and the least recently accessed element is returned last. Only the get , put , and putAll methods influence this ordering. accessOrder=false The elements are ordered according to their insertion. This is the default if any of the other LinkedHashMap constructors is used. In this ordering read access to the map has no influence on element ordering. removeEdlestEntry(Entry) The second feature of
Mehr anzeigen

OSGi Framework Extension as a Maven Project

In a previous post I explained how to extend an OSGi framework such that more classes are visible inside the framework from the outside world. This posting provided a very simple example to generate Framework Extension Bundle using a single file and calling the JAR tool from the command line. Here I will expand on this example by creating a Maven 2 project, which may be used in environments where Maven 2 is used for project builds. As a first step, we need a Maven 2 project descriptor. To create this beast, we have to decide, how we build the project. I generally use the Apache Felix Maven Bundle Plugin to build my projects as OSGi bundles. This great plugin comes with support for Maven 2 packaging but also provides goals to call if the packaging functionality should not be used. Before talking too much, let me just present a project descriptor, which I know works. After that I will explain why I did it, like I did it. <project xmlns="http://maven.apache.org/POM/4.0.0"
Mehr anzeigen