Version 39
Created by ivelin.ivanov on Nov 22, 2004 1:57 PM. Last modified by andy.miller on Apr 17, 2012 11:19 AM.

    JBoss Project Version Convention

    Project versions will follow the OSGi conventions for release names.  As you follow the naming conventions below, you will note that they do not follow the Maven standards for naming and ordering (case is intented to be what is specified below).  The reason for this was fairly simple.  We did not want to depend on a specific build tools naming and ordering rules, because those things tend to change over time.  While Maven is the popular choice today, even at this time, there are other build systems that are growing in popularity, and may supplant Maven as the dominant build system some day.  While that may or may not happen, the point is, things change, and we wanted to be independent of those disruptions.


    The OSGi core specification section 3.2.4 specifies the following:

     

    3.2.4 Version
          Version specifications are used in several places. A version token has the fol-
          lowing grammar:
             version        ::=
                major(    '.' minor ( '.' micro ( '.' qualifier )? )? )?
             major          ::= number                         // See 1.3.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.

     

    The way to read this is that the first number is the major release number, and it is required.  Major, minor and micro release numbers are separated by a period, and minor and micro release number qualifiers are optional.  Finally, there is also a period separated qualifier that is also optional.  The major, minor and macro tokens are numeric, and the qualifier can be alphanumeric, and can have either an underscore or a dash separating additional alphanumeric tokens in the qualifier.  Besides this, we need to understand how versions will be resolved, in terms of which is newer, older, the same, and this is specified in section 3.5.3:

     

    3.5.3 Bundle-Version
          Bundle-Version is an optional header; the default value is 0.0.0.
              Bundle-Version ::= version          // See 3.2.4


          If the minor or micro version components are not specified, they have a
          default value of 0. If the qualifier component is not specified, it has a default
          value of the empty string ("").


          Versions are comparable. Their comparison is done numerically and
          sequentially on the major, minor, and micro components and lastly using
          the String class compareTo method for the qualifier.


          A version is considered equal to another version if the major, minor, micro,
          and the qualifier components are equal (using String method compareTo).


          Example:
              Bundle-Version: 22.3.58.build-345678

     

    The critical part of what section 3.5.3 states is that the String class compareTo method is how to determine which release is newer, older, equal.  This method is defined in the Javadoc as follows:

     

    compareTo

    public int compareTo(String anotherString)
    Compares two strings lexicographically. The comparison is based on the Unicode value of  each character in the strings. The character sequence represented by this String object is compared lexicographically to the character sequence  represented by the argument string. The result is a negative integer if this String object lexicographically precedes the argument string. The result is  a positive integer if this String object lexicographically follows the argument string. The result is  zero if the strings are equal; compareTo returns 0 exactly when the equals(Object) method would return true.
    This is the definition of  lexicographic ordering. If two strings are different, then either they have different characters at some index that is a valid index for both strings, or their lengths are different, or both. If they  have different characters at one or more index positions, let k be the smallest such index; then the string whose character at position k has the smaller value, as determined by using the < operator,  lexicographically precedes the other string. In this case, compareTo returns the difference of the two character values at position k in the two string -- that is, the value: 
     this.charAt(k)-anotherString.charAt(k)
    If there is no index position at which they differ, then the shorter string lexicographically precedes the longer string. In this case, compareTo returns the difference of the lengths of the strings -- that is, the value: 
     this.length()-anotherString.length()
    Specified by:
    compareTo in interface Comparable<String>
    Parameters:
    anotherString - the String to be compared.
    Returns:
    the value 0 if the argument string is equal to this string; a value less than 0 if this string is lexicographically less than the string argument; and a value greater than 0 if this string is lexicographically greater than the string argument.

    As you can see from this methods Javadoc, the Unicode values of the characters and the length of the given version will actually determine the version order.  This is important depending on the projects development process.  Some projects do pretty standard alpha, beta, etc. releases, while other projects use a milestone release process.  Both are acceptable, and in many cases there are very good reasons for projects to adopt one or the other release process.  For example, in the case of the application server, the team has recently shifted to a milestone approach, because it integrates so many disparate projects that are all in various release stages, some in alpha, some in beta, some GA, etc., that its very hard to pin it down into an alpha, beta, etc. release.  So, this leads us to the practicle application of this standard.

    Current Release Version Conventions (including qualifiers) - Post January 8, 2010

    The release version conventions will fall into two separate cases.  The first case, is when projects are using alpha, beta, etc. releases.

     

    major.minor.micro.Alpha[n]

    major.minor.micro.Beta[n]

    major.minor.micro.CR[n]

    major.minor.micro.Final

     

    Where major is the major release number, minor being the minor release number, and micro being a micro release number.  For the qualifiers, the use of Alpha for early releases that are not API complete, but have usuable new functional capabilities where the community can benefit from those new capabilites, plus contribute to the testing and fixing of those new capabilities.  An Alpha release number, such as 1, 2, 3, etc. is optional.  If multiple releases aren't going to be released, then just using Alpha is perfectly acceptable.  The use of Beta qualifier is for releases where the release is API complete, but its not completely tested, or there may even be questions about the API itself, that may change, even though the implementation is complete.  Again, there is the optional numeric that can be used if multiple Beta releases are anticipated.  The use of the CR (Candidate Release) qualifier is for releases that we anticipate can be the GA release, but we need the community to help validate the release.  Again, there is an optional numeric qualifier that can be added if there is a need for multiple CR releases.  Finally, the use of the Final qualifier is for completed releases for the community.


    The use of these qualifiers maintains the release ordering as specified by the OSGi specification.  That brings us to case number two, which is projects that chose to use milestone releases, instead of the more traditional alpha, beta, etc., nomenclature.

     

    major.minor.micro.TIMESTAMP-Mn

    major.minor.micro.CR[n]

    major.minor.micro.Final

     

    As you can see we only specify two qualifiers.  The first one is for the milestone releases, and the qualifier starts with a numeric timestamp.  The project can use a timestamp as shown below as it will sort according to the compareTo method of the String class just like any other qualifier.  For example:

     

    YYYYMMDD where YYYY is the four digit year, MM is the two digit month of the year, and DD is the two digit day of the month.

     

    Optionally, if for some reason there is a need to make two releases in the same day, you can add a sequence number to the end of the timestamp.

     

    The next part of the qualifier is the milestone number, where M stands for milestone, and n is the milestone number.  This is not optional like the case of Alpha, Beta, etc., because it is implied in this nomenclature that there will be mulitple milestone releases before a final release is given to the community.

    After all the milestone releases that have added the various functional pieces are complete, and the project and any sub-projects that are integrated are at least at a candidate release stage, then a CR release will follow.  Just like in the traditional model, there may be multiple CR releases depending on the feedback from the community.


    Finally, the Final qualifier is used for the completed release, just like in the traditional case.

    Jar Manifest Headers

    The standard Java version information and OSGI bundle version headers and their usage needs to be defined. The standard Java jar manifest headers should include:

     

    Manifest-Version: 1.0
Created-By: @java.vm.version@ (@java.vm.vendor@)
Specification-Title: @specification.title@
Specification-Version: @specification.version@
Specification-Vendor: @specification.vendor@
Implementation-Title: @implementation.title@
Implementation-URL: @implementation.url@
Implementation-Version: @implementation.version@
Implementation-Vendor: @implementation.vendor@
Implementation-Vendor-Id: @implementation.vendor.id@

    where:

    • Specification-Title: whatever name/standard name the jar implements

    • Specification-Version: the version number

    • Specification-Vendor: JBoss (http://www.jboss.org/)

    • Implementation-Title: name with additional implementation details

    • Implementation-URL: http://www.jboss.org/

    • Implementation-Version: a full implementation version with addition build info. For example: ${version.major}.${version.minor}.${version.revision}.${version.tag} (build: CVSTag=${version.cvstag} date=${build.id})

    • Implementation-Vendor: JBoss by Red Hat, Inc.

    • Implementation-Vendor-Id: http://www.jboss.org/

     

    A Word About Release Announcements and Download Naming Conventions

    Since we have made the split between community releases and long-term stable product releases (introduced in July, 2007 with EAP 4.2), we have been striving to make sure the message is clear with our community about what is and is not a supported product, which brings us to several issues with announcements and downloads of our community releases.

    Release Announcements

    For all announcements of releases of our community projects, we should not use the term GA (General Availability) or Production.  The term Final should be used for releases into the community in place of GA or Production.  The terms GA and Production make it confusing for subscribers, especially those that are used to the old model, where our community releases were supported products.  Since that is not the case anymore, we should no longer use those terms.

    Download Naming Conventions

    The description column on the downloads page should say Final for the release, in place of stable, production or another other description we have used in the past.  Since we are not using the production description anymore, all pre-final releases should also not use the term pre-production.  They can say Milestone, Alpha, Beta, Candidate Release, and we should constrain our descriptions to those terms.

    Roadmaps are in Jira

    The roadmaps for the JBoss projects are found on the JBoss JIRA site http://jira.jboss.com/.

     

    Related

    JBoss OIDs

     

    Referenced by: