This document describes how we handle the versioning of plugins, features, products, installers, and update sites in JBoss Tools and Red Hat CodeReady Studio.
JBoss projects in general follows the general naming at https://community.jboss.org/wiki/JBossProjectVersioning.
Plugins/features and even other components should be versioned according to http://wiki.eclipse.org/Version_Numbering
The rest of this document tries to cover what is not specified in these two documents and if there are exceptions to it.
Component - generic term used for something that is versioned. Could be a plugin, feature, target platform, product, project, update site, etc.
Module - A set of components, for example: https://github.com/jbosstools/jbosstools-hibernate/ or https://github.com/jbosstools/jbosstools-base
Both JBoss and OSGi versioning rules say there are four parts to the versioning scheme.
JBoss refers to these as: major.minor.micro.qualifier
Eclipse & OSGi use: major.minor.service.qualifier
We consider these to be equal, i.e. micro == service.
JBoss rules state the numeric option on qualifiers are optional, i.e. Alpha is ok without a number. We always add the number for consistency and that we know we are more than likely to have multiple of them.
The only qualifier that cannot have a numeric is Final. Final is final.
When you do development you choose the right x.y.z for the next upcoming/planned release, i.e. 4.4.0.
A 4.4.0 that is all new and going to be used by other in-development components starts out by being named 4.4.0.AM1 and then progress through bumping the qualifier until you reach 4.4.0.Final.
Example:
4.4.0.AM1 4.4.0.AM2 4.4.0.AM3 4.4.0.Final
The exact number of AMx milestones is 3, but sometimes one might be dropped due to staffing concerns (eg., over December or summer holidays). So a build will always be produced after each 3 week sprint, but it may not be released if it’s not ready for consumption.
We used to increment from Alpha to Beta to CR, but now that we have a clear 3-sprint cycle of AMx milestones, followed by a sprint cycle to Final/GA, that differentiation of quality is no longer required. Instead, we simply have AM1, AM2, AM3, then Final or GA.
The simple rule is that a component goes Final once itself and all its subcomponent are Final.
This rule should be uphold and any deviance from it considered bad and fixed. If it happens be clearly agreed and documented on which subpart has issues.
Once the release have gone final, i.e. 4.4.0.Final the qualifiers cannot "move" more for that micro release. After this the component dependent on its development pase and phase do either a full development cycle:
4.4.1.AM1 4.4.1.AM2 etc.
If the changes are pure and simple bugfixes and you got plenty of tests to verify this you can directly do
4.4.1.Final
Example: you just released 4.4.0.Final and minutes/hours after a serious bug is found in your component or a subcomponent. What to do ?
Fix the bug/upgrade to the subcomponent that does not have the bug and version accordingly which hopefully would be just 4.4.1.Final.
In the worst case that the subcomponent needs to be upgraded to something that breaks/adds API you would need to do a 4.5.0 instead - but in that case you cannot just do a 4.5.0.Final directly. This would require a new development phase - thus should be avoided at all costs by getting the subcomponent fixed without breaking API.
This concerns how we handle versioning conflicts between streams.
Let’s say if you have a component versioned 4.4.0 just released as part of JBoss Tools 4.4/Developer Studio 10.0 and a new major development starts for JBoss Tools 4.5/Developer Studio 11.0 - what do you do with the component versioned at 4.4.0 ?
The general rule is as follows:
When it’s time to branch between maintenance (eg., 4.4.x) and master branch, you should upversion your features & plugins:
-
in the maintenance stream to x.y.z+1 (eg., 4.4.1, 4.4.2), and
-
in the master stream to x.y+1.0 (eg., 4.5.0) or, if you can guarantee your master branch stuff works w/ the previous version of Eclipse, then x.y.10z (eg., 4.4.100, 4.4.101)
Thus given the example above you have choice between bumping the minor (y) or micro with +100, but the current default is to bump the minor version to get 4.5.0 to avoid promising something we are not actually verifying.
The question often asked is why not just rely on bump to 4.5.1 or 4.5.100 as done in some Eclipse.org projects ?
The main reasons for this is:
-
if bumping to 4.5.1 in the new branch, the old branch can no longer do maintenance updates (bad)
-
if bumping to 4.5.100 that is solved and is definitely a good model to strive for, but since we are in a new development stream moving from i.e. Kepler to Luna you are changing the build and test dependencies and are you then confident enough to say your component still works on Kepler ? (it should since you haven’t bumped the major version)
Thus historically we’ve bumped the minor version between development streams since then there are no false promises about backwards compatibility.
Why do I need to bump my module in a bundle that has no code changes when another bundle in the bundle changes for a maintenance release ?
This situation occurs when you have multiple components in one module (repository).
For example base has both foundation and common and they were released as foundation-1.2.0.Final and common-4.5.0.Final.
For a maintenance release foundation has a bugfix made and according to the basic OSGI/JBoss versioning rules above it bumps to at least foundation-1.2.1.Final. Now what should common do ?
Most would say common should not need to bump its version since it has not changed, but unfortunately that assumes that common is not being rebuilt either.
In the current setup of JBoss Tools builds the whole repository is rebuilt and published as one updatesite, which means common will be rebuilt and thus will as a minimum get a new timestamp in the qualifier (i.e. 4.5.0.Final-v20140912-2255-B61 and 4.5.0.Final-v20141011-2258-B67) and that again breaks the basic versioning rules of artifacts.
Thus if you do not bump common it will A) have done different binary releases of the same version B) still result in updates to the user anyway.
Thus the policy is that if a module gets rereleased all bundles/components withint it needs to at least bump the micro version no matter if they had changes or not.
It is unfortunately not yet possible to predict what API changes we will make to know what the right version will be, but what we can do is to detect what definitely looks like a wrong version. In https://issues.jboss.org/browse/JBIDE-19056 we enabled explicit version checking against the latest public release of JBoss Tools.
Now if a plugin have been part of a release and you build locally using a non-bumped version you will get an error like this:
[INFO] org.jboss.tools.openshift.egit.core ............... FAILURE [9.173s]
[ERROR] Failed to execute goal org.jboss.tools.tycho-plugins:repository-utils:1.0.0-SNAPSHOT:compare-version-with-baselines (default)
on project org.jboss.tools.openshift.egit.core: Version of 'org.jboss.tools.openshift.egit.core/2.6.0.AM1-v20150128-1932) must be bigger than baseline one (2.6.1.Final-v20141209-0337-B67) -> [Help 1]Explaining that there is a problem with the versioning string which can then be handled.
For more on how baseline checks work, see Building with Maven Enforcer Checks & Baseline Comparisons.