Version Numbering
- Craig Gallen [Administrator] (Unlicensed)
JOSIF Main Page | Version Numbering
Introduction
This is an initial proposal for version numbering of TIP Framework components. The proposed scheme is being used to populate the bug tracker and tag the first interim release of the framework projects. A primer on moving projects between release numbers is provides at Updating Project Versions
A version numbering scheme is essential in order to tag issues and future roadmap items on the bug tracking system. The scheme must be applicable both to the tagged releases managed in the sourceforge subversion repository and to the components uploaded to the maven repository.
The proposed scheme draws upon the Linux kernel numbering scheme and a similar scheme used successfully in OpenNMS for Stable, development, and Release candidate numbering. In principle there are three parts to the version number:
For a three part version number in the form M.N.O:
M - Major number e.g.*1.0.0 Represents very significant changes
N - Minor number e.g. 1.*0.0: Indicates the release; even numbers are production and odd numbers are development
O - Micro number/Patch level e.g. 1.0.*11: Indicates bug fixes and updates.
To allow identification of release candidates, we use the convention of
- Development: Odd Minor Number with the Micro Number (O) less than (<) 90 is a development release. e.g. 1.0.11 would be a development release.
- Release candidate (i.e. a beta release): Odd Minor Number with the Micro Number (O) Greater than or equal to (>=) 90 is the release candidate for the next stable release M.(N+1).0. e.g. 1.1.90 would be a release candidate for 1.2.0
Maven Release Numbering primer
Because we are using Maven to manage the released artefacts, we need also to consider Maven's release numbering system. Keeping our version numbers aligned with this standard will become very important if we start using version ranges in our pom.xml files.
Maven versions contain the following parts: major version, minor version, incremental version, and qualifier. In a version, these parts correspond to the following format:
<major version>.<minor version>.<incremental version>-<qualifier>
For example, the version "1.3-beta-01" has a major version of 1, a minor version of 3, and a qualifier of "beta-01".
Note that although qualifier strings to signify alpha / beta etc are allowed, we will confine ourselves to simply use the numbering scheme described above.
Maven versions can contain a string literal SNAPSHOT to signify that a project is currently under active development. For example if the next release of your component is going to have a version "1.4.1", your project would have a version "1.4.1-SNAPSHOT" until it was formally released. When deploying a SNAPSHOT version, Maven expands the SNAPSHOT tag with the date and time of the release. If your project has a version of “1.0-SNAPSHOT” and you deploy this project’s artifacts to a Maven repository, Maven would expand this version to “1.0-20080207-230803-1” if you were to deploy a release at 11:08 PM on February 7th, 2008 UTC.
If projects are in a subversion trunk, they should use the SNAPSHOT tag. When they are released, they should be copied into the tags section of subversion and no longer have the SNAPSHOT label applied in their pom.xml. This is described further below.
See the Maven Handbook for more information on this subject.
Version Numbering applied to the TIP Framework
The proposed numbering scheme works well from the first release (1.0) of the Framework but requires a little modification for pre-release versions.
Prior to Framework 1.0 release - use 0 as Major number and 0 as Release number 0.0.x-SNAPSHOT - Latest version on development trunk (Head) 0.0.1 tagged interim development release<BR/> 0.0.2 tagged interim development release<BR/> ...<BR/> 0.0.90 Release candidate (Beta 1)<BR/> 0.0.91 Release candidate (Beta 2)<BR/> 1.0.0 First Stable Framework Release<BR/> 1.0.x Minor bug fixes etc<BR/> <BR/> Subsequent development would happen in the 1.1.x stream<BR/> 1.1.x-SNAPSHOT - Latest version on development trunk (Head)<BR/> 1.1.1 tagged interim development release<BR/> 1.1.2 tagged interim development release<BR/> ...<BR/> 1.1.90 Release candidate (Beta 1)<BR/> 1.1.91 Release candidate (Beta 2)<BR/> 1.2.0 Stable Release<BR/> 1.2.x Minor bug fixes etc<BR/>
Version Numbering applied to sub components of the TIP Framework
The Sub components of the TIP Framework should follow broadly the same version numbering of the overall framework but will be subject to their individual development life cycles up until the final integration of a given framework release. Thus they should inherit the Major and Minor numbers from the TIP Framework release but the Micro Number should increment as the plugin is developed through its release cycles. Thus for example the Framework 1.0.2 release might theoretically reference the following releases of the plugins;
(Theoretical example of Framework 0.0.2 release)<BR/> TIP_Doc_Generator Release 0.0.10<BR/> TIP_Profile Release 0.0.5<BR/> TIP_Soap_Generator Release 0.0.7<BR/> TIP_Project_Creator Release 0.0.10<BR/> <BR/> Projects against which this framework release was regression tested<BR/> TIP_Fmk_Test1 Release 0.0.7<BR/> TIP_Fmk_Test2 Release 0.0.9<BR/>
When the Framework is finally released as version 1.0.0, the plugins, profiles and test projects would also be tagged and released as final versions accompanying that version of the framework:
(Theoretical example of Framework 1.0.0 release)<BR/> TIP_Doc_Generator Release 1.0.0<BR/> TIP_Profile Release 1.0.0<BR/> TIP_Soap_Generator Release 1.0.0<BR/> TIP_Project_Creator Release 1.0.0<BR/> <BR/> Projects against which this framework release was regression tested<BR/> TIP_Fmk_Test1 Release 1.0.0<BR/> TIP_Fmk_Test2 Release 1.0.0<BR/>
Version numbering applied to Tigerstripe Generators
The Tigerstripe generators present a special case in that it is important NOT to change the number of the generator in it's ts-plugin.xml unless the properties associated with the Generator have actually changed. This is because it will mess up all of the projects tigerstripe.xml files if it changes without reason. Thus the ts-plugin.xml should contain the number of the ultimate Framework release (e.g. 0.1.0) and NOT be changed. The pom.xml for the particular interim release should however contain the current release number 0.0.1 etc.
Version Numbering applied to individual files
Where documentation in a file may refer to changes since the last SNAPSHOT release, a 4th number is required to identify the change within the SNAPSHOT. For example the documentation in a pom.xml file header may look like this;
<!--**********************************************************************************************--> <!-- TIP_Profile_Package pom.xml --> <!--**********************************************************************************************--> <!-- Documentation : --> <!-- This project packages and deploys a Tigerstripe generator to a maven repository --> <!-- --> <!-- Author: Craig Gallen --> <!-- Date: 22-6-09 --> <!-- Version : 0.0.1.1 --> <!--**********************************************************************************************--> <!-- Change History --> <!-- Version 0.0.1.1 03-08-09 Craig Gallen - changed to 0.0.1-SNAPSHOT & base to 0.0.1-SNAPSHOT --> <!-- Version 0.0.1.0 22-6-09 Craig Gallen - Initial Archetype Version --> <!--**********************************************************************************************-->
Here Version 0.0.1.1 refers to the first revision on the 0.0.1-SNAPSHOT
Version Numbers in Subversion
Subversion applies a new version number to the whole repository with each commit. In theory, this version number could be used to find a set of artifacts at a given instance in time. However, usual practice is not to rely on this mechanism for release management but rather use a system of tagged releases which clearly identify the content of a given released artifact. This section describes how release tagging will be done in the TIP project.
The structure of the subversion repository is described under Project Structure.
Each sub project has it's own arrangement of tags, branches and trunk working sets as illustrated below.
NOTE THIS IS FOR ILLUSTRATION ONLY - IT MAY NOT MATCH THE ACTUAL VERSIONS IN SUBVERSION<BR/> tip (Root of TIP project)<BR/> .. framework - location of framework projects - soap and documentation generators etc<BR/> .... TIP_Framework_BaseProject<BR/> ........ tags<BR/> ............... RELEASE_1_0_1 (NOTE This is also the release number in the released pom)<BR/> ....................... TIP_Framework_BaseProject<BR/> ........ branches<BR/> ........ trunk<BR/> ............... TIP_Framework_BaseProject<BR/> .... TIP_Soap_Generator<BR/> ........ tags<BR/> ............... RELEASE_1_0_2 (NOTE This is also the release number in the released pom)<BR/> ....................... TIP_Soap_Generator<BR/> ....................... TIP_Soap_Generator_Package<BR/> ............... RELEASE_1_0_3<BR/> ....................... TIP_Soap_Generator<BR/> ....................... TIP_Soap_Generator_Package<BR/> ........ branches<BR/> ............... 1_0_4<BR/> ....................... TIP_Soap_Generator<BR/> ....................... TIP_Soap_Generator_Package<BR/> ........ trunk<BR/> ................ TIP_Soap_Generator<BR/> ................ TIP_Soap_Generator_Package<BR/>
Normally development will take place in the trunk stream. Projects in the trunk stream should have SNAPSHOT appended to their version number and as discussed above, their release number should be ODD to indicate this is a development stream. When a project is to be released it should be copied to a tagged release under tags - as illustrated above. It's version number fixed and no longer SNAPSHOT (e.g. 1.0.1-SNAPSHOT become 1.0.1 ). The project should be built along with its maven generated web site and the artifacts posted to the maven repository with the correct version number.
Note that the projects under the tags branch should be contained in a sub folder named after the release as shown below:
RELEASE_M_N_O
Where M is the Major number, N is the Minor number and O is the Micro number as described above. e.g.
RELEASE_1_0_1
Use of Branches for Maintenance
The projects stored under tags should only be used for releases. Once a release has been tagged, the files in the tagged release should not be further updated but left as a record of the content of that release.
Branches can be used for any activities needing performed outside of the trunk stream. In particular, branches should be used for maintenance. If maintenance needs to be performed on a tagged release, it should be copied to a branch and the updates performed and tested on the branch. Once the branch is ready for releasing, it should be copied back as an updated tagged release and released.
Note that maintenance projects under the branches branch should be contained in a sub folder named after the release as shown below:
M_N_O
Where M is the Major number, N is the Minor number and O is the Micro number as described above. e.g.
1_0_4