Version Number Strucuture

The versions of ConnId framework consist of four numbers:

1.X.Y.Z

The numbers have the following meaning:

• 1: Major version. If it is ever going to change it will mean total loss of compatibility. A complete new framework.
• X: Minor version. The number is increased if there is significant progress in framework features. Deprecated functionality may be removed, so there may be slight (but still controlled) incompatibility when the minor version number changes.
• Y: Subminor version. The number is Increased if there are bugfixes or smaller incremental feature additions. The versions that have just the subminor version increased are supposed to maintain 100% backward compatibility. 
• Z: Joker. Official ConnId releases always use zero (0) at this position. The joker number is a mechanism that anybody can use to create a unofficial release of ConnId framework and still keep reasonable level of sanity and compatibility (see below).

Versioning of Official ConnId Releases

The official ConnId releases are created by a ConnId project maintainer when a consensus about the release is reached on the project mailing list. Official ConnId framework releases are intended for general use and the use of these releases is strongly recommended.

Versioning of Unofficial ConnId Releases

Motivation: The ConnId framework is used by several projects. These projects are generally quite agile and they have different goals and procedures. Sometimes it is difficult to align the quality, procedure and timing requirements of all the major ConnId users and create an official ConnId release exactly when needed. Although the use of unofficial ConnId releases is discouraged we have to admit that this practice is sometimes necessary. This lead to "creative" version numbers in the past, e.g. versions such as "1.4.0.e1". Such version numbers were used by some teams to mark unofficial, team specific ConnId releases. However the use of such versioning mechanism is confusing as it is difficult to see how versions "1.4.0.e1" and "1.4.0.rc3" relate to each other with respect to compatibility. Therefore the use of such "creative" version numbers is now not recommended. The use of the "joker" version is the recommended practice.

To create an unofficial ConnId framework release the "joker" is used in a simple numeric form without any prefix. We assume that the unofficial ConnId release is compiled from the master branch of the official ConnId development repository. In such a case the "joker" number should represent the number of commits since the last official release. This can be slightly tricky to determine in git repository, but a common practice of using the "git describe" command is recommended. E.g. if git describe gives "connid-1.4.0.0-25-g9bcddd5" the version 1.4.0.25 should be used for a release created from this source code. A release produced like this can be (relatively) safely published it in maven repositories and used as a dependency. As the official releases will always end with ".0" this is unlikely to clash with any official version. It is also very likely that two people doing the same build from the same source tree will end up with a compatible code anyway. So this should work well even without strong central coordination.