Need a consistent version numbering convention

[starksm64]

We need some consistency in the numbering convention. How does one compare a version like 1.2.4_SP1_FINAL to 1.2.4.1 or 1.2.4beta1?

The jboss build as well as eclipse and more generally osgi bundles have a notion of versions and expressions of compatibility between versions that needs to be computable. We have a problem with being able to update to the latest 1.5.0 release of the ide from 1.5.0RC2 because of this. We need a consistent versioning convention that is going to work in these version comparison scenarios.

I'll post more about the osgi bundle versioning as a starting point.

[starksm64]

A grab of the current build-thirdparty.xml version description yields many uncertain version strings in terms of comparisons between versions: 2.7.5H3 1.2b3 0.2-cvs 1.0.4.1jboss 3.1beta6 cvs-7-19 2.0.x

 <componentref name="antlr" version="2.7.5H3"/>
 <componentref name="apache-addressing" version="cvsbuild-7-19"/>
 <componentref name="apache-avalon" version="4.1.5"/>
 <componentref name="apache-avalon-logkit" version="1.2"/>
 <componentref name="apache-bcel" version="5.1"/>
 <componentref name="apache-beanutils" version="1.6.0"/>
 <componentref name="apache-bsf" version="2.3.0"/>
 <componentref name="apache-codec" version="1.2.0"/>
 <componentref name="apache-collections" version="2.1"/>
 <componentref name="apache-crimson" version="1.1.1"/>
 <componentref name="apache-digester" version="1.6"/>
 <componentref name="apache-discovery" version="0.2"/>
 <componentref name="apache-fileupload" version="1.0"/>
 <componentref name="apache-httpclient" version="2.0.2"/>
 <componentref name="apache-jaxme" version="0.2-cvs"/>
 <componentref name="apache-lang" version="1.0"/>
 <componentref name="apache-log4j" version="1.2.8"/>
 <componentref name="apache-logging" version="1.0.4.1jboss"/>
 <componentref name="apache-myfaces" version="1.1.0"/>
 <componentref name="apache-pool" version="1.0.1"/>
 <componentref name="apache-scout" version="1.0"/>
 <componentref name="apache-slide" version="1.0.16"/>
 <componentref name="apache-slide" version="1.0.16"/>
 <componentref name="apache-tomcat" version="5.5.12"/>
 <componentref name="apache-velocity" version="1.4jboss"/>
 <componentref name="apache-wss4j" version="cvs-7-19"/>
 <componentref name="apache-xalan" version="j_2.6.0"/>
 <componentref name="apache-xerces" version="2.7.0"/>
 <componentref name="apache-xmlsec" version="1.2"/>
 <componentref name="asm" version="1.5.3"/>
 <componentref name="beanshell" version="1.3.0"/>
 <componentref name="cglib" version="2.1.2jboss"/>
 <componentref name="dom4j" version="1.6.1jboss"/>
 <componentref name="gjt-jpl-util" version="1.0"/>
 <componentref name="gnu-getopt" version="1.0.10"/>
 <componentref name="gnu-regexp" version="1.1.14"/>
 <componentref name="hibernate" version="3.1rc2jboss"/>
 <componentref name="hibernate-annotations" version="3.1beta6"/>
 <componentref name="hibernate-entitymanager" version="3.1beta4"/>
 <componentref name="hsqldb" version="1.8.0.2"/>
 <componentref name="ibm-wsdl4j" version="1.5.1"/>
 <componentref name="jacorb" version="2.2.1jboss"/>
 <componentref name="javassist" version="3.1RC2"/>
 <componentref name="jaxen" version="1.1beta4"/>
 <componentref name="jboss/aop" version="1.3.4"/>
 <componentref name="jboss/cache" version="1.2.4_SP1_FINAL"/>
 <componentref name="jboss/microcontainer" version="1.0.1"/>
 <componentref name="jboss/jbossws" version="snapshot"/>
 <componentref name="jboss/jbossxb" version="snapshot"/>
 <componentref name="jboss/remoting" version="1.4.0_beta"/>
 <componentref name="jboss/serialization" version="1.0.0.RC2"/>
 <componentref name="jfreechart" version="0.9.20"/>
 <componentref name="jgroups" version="2.2.7"/>
 <componentref name="joesnmp" version="0.3.3"/>
 <componentref name="juddi" version="0.9RC4"/>
 <componentref name="junit" version="3.8.1"/>
 <componentref name="junitejb" version="1.4"/>
 <componentref name="objectweb-joramtests" version="1.1"/>
 <componentref name="odmg" version="3.0"/>
 <componentref name="oswego-concurrent" version="1.3.4"/>
 <componentref name="qdox" version="1.4"/>
 <componentref name="retrotranslator" version="0.9.5"/>
 <componentref name="sleepycat" version="1.5.2"/>
 <componentref name="sun-jaf" version="1.0.2"/>
 <componentref name="sun-javacc" version="3.2"/>
 <componentref name="sun-javamail" version="1.3.1"/>
 <componentref name="sun-servlet" version="2.4"/>
 <componentref name="trove" version="2.1.1"/>
 <componentref name="wutka-dtdparser" version="1.2.1"/>
 <componentref name="xdoclet" version="1.2b3"/>
 <componentref name="xml-sax" version="2.0.x"/>

[koen.aers]

Most Eclipse projects don't follow the rules either. AFAI have heard, the only Eclipse project bumping the release number at each release is EMF. The other ones are also having RCx and Mx releases with the same problems as occurring with our own IDE.
Unfortunately, I think there is no elegant solution for this. Assume I am going to work on the 3.1 branch of my jBPM plugin. The current release is 3.0.6. What will the release tag of the next release in the 3.1 branch be?
If I choose it to be 3.1.0 then I have a problem if I want to have some alpha and beta releases before releasing the final. The only thing I can come up with is indeed, as suggested in the IDE user's forum to have a character suffix. But then this feels really weird...
Another solution, but maybe equally weird could be to prepend a character before the release number in case of alpha or beta releases. This would then look like 3.1.a1 or 3.1.b2 or 3.1.c3. But then I am not sure that 3.1.a1 comes before or after 3.1.0...

Regards,
Koen

[starksm64]

The OSGi R4 version syntax is:

3.2.4 Version
Version specifications are used in several places. A version token has the following grammar:

version ::=
major( '.' minor ( '.' micro ( '.' qualifier )? )? )?
major ::= number // See 1.4.2
minor ::= number
micro ::= number
qualifier ::= ( alphanum | ?_? | '-' )+

A version token must not contain any white space. The default value for a
version is 0.0.0.

3.2.5 Version Ranges
A version range describes a range of versions using a mathematical interval notation. The syntax of a version range is:

version-range ::= interval | atleast
interval ::= ( '[' | '(' ) floor ',' ceiling ( ']' | ')' )
atleast ::= version
floor ::= version
ceiling ::= version

If a version range is specified as a single version, it must be interpreted as the range [version,?). The default for a non-specified version range is 0, which maps to [0.0.0,?).

[starksm64]

So the only supported syntax for non-numeric is major.minor.micro.alphanum

To your examples:

3.1.a1 would have to be 3.1.1.a or 3.1.1.alpha

The key thing is coming up with a convention such that within a set of versions there are meaningful comparisons. I'll take a look at the eclipse osgi framework implementation to see how the alphanum is handled to see what convention could be used for comparision.

[admin]

the OSGi R4 stuff looks good to me. the only thing we need to add is an ordering in the qualifiers. i believe we have this ordering in the wiki somewhere.

regards, tom.

[maxandersen]

what is needed is a fourth discriminator which is also ordered; but only used for "marks", e.g. alpha, beta, gamma, rc, ZERO.

And 1.5.0 should then be 1.5.0.ZERO (ZERO because it is a 0, but need to be in the end of the alphabet if alpha, beta, gamme, rc, etc. is allowed.

1.5.0.0 is not good enough since its the lowest of all.

[koen.aers]

"Max" wrote:
1.5.0.0 is not good enough since its the lowest of all.

This is precisely the problem. But adding a string like 'zero' as qualifier seems a bit awkward to me. It seems there is no other solution though...

[mikek753]

the build # could be used as well that would be increased indeed
and then in description for the product you put what is it (a1, b2 or rc1 or just version)

basicaly you assign Product version to the build #, where versioning is done via build #

Many other products use build #, that's why you may see ppl talk about build # instead version #

that will also solve problem with update for nightly builds - IMHO.

[marklittle]

I think the OSGI format looks good. For what it's worth, the versioning scheme we've used for the past 10+ years for the transaction service has been:

___[Alpha | Beta][_RC<number] | GA]

where components within [] were optional.

Build numbers were additional to this and encoded within the product and associated meta-data.

Mark.

[marklittle]

OK, once again and remembering HTML ;-)!

I think the OSGI format looks good. For what it's worth, the versioning scheme we've used for the past 10+ years for the transaction service has been:

{product}_{major}_{minor}_{minorminor}[Alpha | Beta][_RC<number] | GA]

where components within [] were optional.

Build numbers were additional to this and encoded within the product and associated meta-data.

Mark.

[mculpepper]

One thing we should also remember is that including build numbers inside of the version identifier can be confusing to users of the IDE, since the plugin and feature directories have the version number embedded directly into the folder name, i.e.:

eclipse/plugins/org.jboss.ide.eclipse.core_1.5.0.REALLYLONGBUILDNUMBER

[ben.wang]

How about service pack (e.g., sp1) naming? Is it just external one?

-Ben

[starksm64]

The version implementation included with the osgi framework classes simply interprets the qualifier element of a version using string compare, and so the qualifier prefix is what has to be consistent to establish a consistent version convention. A final release with an implicit qualifier of 0 is the lowest of any x.y.z.q number as Max said, so whatever the convention alpha, beta, RCn, SPn, etc., the qualifier convention has to result in correct comparision. This also applies to case. "alpha".compareTo("RC1") is in fact gt 0, while "Alpha".compareTo("RC1") lt 0.

package org.osgi.framework;
public class Version implements Comparable {
 private final int major;
 private final int minor;
 private final int micro;
 private final String qualifier;
...
 /**
 * Compares this <code>Version</code> object to another object.
 *
 * <p>
 * A version is considered to be <b>less than </b> another version if its
 * major component is less than the other version's major component, or the
 * major components are equal and its minor component is less than the other
 * version's minor component, or the major and minor components are equal
 * and its micro component is less than the other version's micro component,
 * or the major, minor and micro components are equal and it's qualifier
 * component is less than the other version's qualifier component (using
 * <code>String.compareTo</code>).
 *
 * <p>
 * A version is considered to be <b>equal to</b> another version if the
 * major, minor and micro components are equal and the qualifier component
 * is equal (using <code>String.compareTo</code>).
 *
 * @param object The <code>Version</code> object to be compared.
 * @return A negative integer, zero, or a positive integer if this object is
 * less than, equal to, or greater than the specified
 * <code>Version</code> object.
 * @throws ClassCastException If the specified object is not a
 * <code>Version</code>.
 */
 public int compareTo(Object object) {
 if (object == this) { // quicktest
 return 0;
 }

 Version other = (Version) object;

 int result = major - other.major;
 if (result != 0) {
 return result;
 }

 result = minor - other.minor;
 if (result != 0) {
 return result;
 }

 result = micro - other.micro;
 if (result != 0) {
 return result;
 }

 return qualifier.compareTo(other.qualifier);
 }

[maxandersen]

Here is a fresh article (at least for me) that describes how eclipse is going to solve it.

http://www.eclipse.org/equinox/documents/plugin-versioning.html

I'm not completely sure this is a good strategy, but at least there is a strategy now for eclipse *3.2* (not 3.1) plugins.