Versions
This page documents the proposal for a version numbering scheme for all ProgClub projects.
Version numbers will be in the format Major.Minor.Revision.
Major version
The major version is an integer starting from '0' (for the initial development), incremented to '1' for the first "production quality" release, and thereafter incremented to '2', '3', etc., as successive major versions are released.
If a new release is going to be incompatible with a previous release then the major version number should definitely be incremented. The major version number can be incremented even if a release is compatible with a previous major version release, and it might be incremented to indicate that significant new functionality has been added. If you are going to be releasing a new version of a project but will need to provide maintenance for a previous version then the major version should be incremented so that maintenance on the previous major version can continue.
Minor version
The minor version is an integer starting from '0' (except for the major version '0' where the first minor version is '1'). The minor version is incremented to an even number for all releases, and then incremented to an odd number for the next development version. So a project will start life at development version 0.1, then might have its first release for 0.2, then go into development as version 0.3, then might have another release for 0.4, then go into development as version 0.5, then development version 0.5 might be released as the next major version so it would be released as version 1.0, then go into development as version 1.1, then might have another release for version 1.2, then go into development as version 1.3, and so on.
Revision
The revision is a revision number from the subversion version control system that the project source code is kept in. Revision numbers are managed by subversion and an applicable revision number that indicates the state of the repository when a project was released is selected and used as the revision number for a release. For development versions the revision number is not kept up to date and is essentially irrelevant. A successive development version will have the same revision number as the previous release (but the minor version will have been incremented to the next odd number).
Files
Every project will have five files in the project root, being: VERSION.MAJOR, VERSION.MINOR, VERSION.REVISION, VERSION and RELEASE. The VERSION.MAJOR file has a single integer greater than or equal to '0' being the major version of the software under development. The VERSION.MINOR file has a single integer greater than or equal to '0' being the minor version of the software under development. The VERSION.REVISION file has a single integer greater than or equal to '1' being the revision of the last (or current) release. The VERSION file is updated based on the contents of the VERSION.MAJOR, VERSION.MINOR and VERSION.REVISION files with a full version number in the form Major.Minor.Revision. The RELEASE file contains the UTC date and serial number of the current release in the format YEAR-MONTH-DAY-SERIAL, where YEAR is a four digit year, MONTH a two digit month, DAY a two digit day and SERIAL a three digit serial number starting at '001'. For a development version the RELEASE file contains the work 'development' as there is no corresponding release for a development version.
Branches
The code for the latest major version lives in project/trunk. When a major version is incremented project/trunk is branched into project/branches/version/MAJOR where MAJOR is the previous major version, e.g. '0', '1', etc. So you start work on development version 0.1, you do one beta release 0.2 and then continue development in 0.3. You decide to release version 0.3 as version 1.0, so first you branch project/trunk to project/branches/version/0 keeping a copy of the major version 0 from project/trunk, then in project/trunk you update the VERSION.MAJOR file to be '1', the VERSION.MINOR file to be '0', the VERSION.REVISION file to be the HEAD subversion revision, the VERSION file to be the Major.Minor.Revision, and then you tag project/trunk as a release in project/tags/version/1/0. Then you increment the VERSION.MINOR file in project/trunk to put it back in development mode at minor version '1'. You then have version 1.1 under development in project/trunk, version 0.3 under development in project/branches/version/0, and version 1.0 released in project/tags/version/1/0. You can then continue development either on the 1.1 branch in project/trunk, or on the 0.3 branch in project/branches/version/0. If you continue development on 0.3 working out of a project/branches/version/0 working copy you might then release a project from this branch as version 0.4, in which case you would increment the VERSION* files in project/branches/version/0 to be at version 0.4, and then tag the release from project/branches/version/0 to project/tags/version/0/4, and then increment the VERSION.MINOR file in project/branches/version/0 to '5'.
Tags
Tags are created in subversion for each release. Releases have even minor version numbers and a revision number that indicates the repository revision they were created from. For each release there are two tags created from the branch being released: tags/version/MAJOR/MINOR and tags/release/YEAR/MONTH/DAY/SERIAL. MAJOR and MINOR are the major and minor version numbers. YEAR is a four digit year of the UTC date of the release. MONTH is a two digit month of the UTC date of the release. DAY is a two digit day of the UTC date of the release. SERIAL is a three digit serial number for releases on that UTC date starting at 001, then 002, up to 999. No more than 999 releases can be done for a project on any given date.
Deprecating major versions
It's possible that you have a scenario like this: you start a project at version 0.1, release at 0.2, develop 0.3, release to 1.0, develop 1.1, release to 2.0, continue development on version 1 as version 1.3, start developing version 2.1, release a maintenance version 1.4, continue development on version 1.5, then you realise that version 2 has gone horribly wrong and should be abandoned, so you release version 1.5 as version 3.0, then begin development on version 3.1. So basically version 1 went to version 2 and version 3, and version 2 became deprecated. So any major version can branch to any future major version.
Processes
Major release
A major release takes a development branch (with an odd minor version) and releases it as the next available major version. For example development version 0.3 in project/trunk might have a major release as version 1.0, where 1.0 will then go into development as version 1.1; or development version 1.1 in project/branches/version/1 might have a major release as version 4.0, where 4.0 will then go into development as version 4.1. A major release is always from a development version to a later major version and a minor version of '0'. So maybe 0.3 to 1.0, 0.5 to 2.0 and 1.1 to 3.0. A major release can be from any branch, including project/trunk, project/branches/version/MAJOR (where MAJOR is the major version number) or project/branches/CUSTOM where CUSTOM can be the name of any custom branch. After a major release project/trunk is replaced with a branch from project/tags/version/MAJOR/MINOR. If you are deprecating a major version (e.g. releasing version 1.3 as version 3.0 thus deprecating version 2) and you will need to still do maintenance on the deprecated version, make sure you branch project/trunk to project/branches/version/MAJOR before you do a major release as a major release will update project/trunk to be the latest major version and if you haven't branched your deprecated major version you will lose it from project/trunk.
Minor release
A minor release is the most typical type of release. For a minor release the major version is left as is in the VERSION.MAJOR file and the minor version is incremented from an odd development version number to an even release version number in the VERSION.MINOR file. The current svn HEAD revision number is recorded in VERSION.REVISION and the VERSION file is updated based on the VERSION.MAJOR, VERSION.MINOR, VERSION.REVISION files. The release name in the format YEAR-MONTH-DAY-SERIAL is determined by looking for an available SERIAL in the project/tags/release/YEAR/MONTH/DAY directory for the current UTC date (if an existing SERIAL of '999' is found then the release is aborted and will have to wait for the next day) and the RELEASE file is updated with the release name. The changes to the VERSION* and RELEASE files are committed to the current branch, then the branch is tagged in project/branches/version/MAJOR/MINOR and project/branches/release/YEAR/MONTH/DAY/SERIAL. Then the VERSION.MINOR version number is incremented to the next odd development version number and the VERSION file updated with the new minor version. The RELEASE file has its contents replaced with the word 'development' and the updated development VERSION* and RELEASE files are committed for the current branch. That leaves the branch in a state for development of the next version and two tags, one for the Major.Minor version and one for the release.
