Difference between revisions of "Versions"

From ProgClub
Jump to: navigation, search
(Designing versioning system.)
 
(Removing version control systems doco...)
 
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
This page documents the proposal for a version numbering scheme for all ProgClub [[projects]].
+
This page documents the proposal for a version numbering scheme for all ProgClub [[projects]]. This versioning system will be designed and documented here first and implemented for all ProgClub projects when it is ready.
  
−
Version numbers will be in the format Major.Minor.Revision.
+
Version numbers will be in the format Major.Minor.Revision as described here. The versioning processes described in this document are to be implemented by the [[pcsvnrelease]] script.
 +
 
 +
= Status =
 +
 
 +
This document is a work in progress.
 +
 
 +
= Components =
  
 
== Major version ==
 
== Major version ==
Line 7: Line 13:
 
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.
 
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.
+
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, i.e. for "political" or "marketing" reasons.
  
 
== Minor version ==
 
== 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.
+
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 so that previous minor versions can go into "maintenance" mode. Generally minor versions are incremented after public or commercial releases of the software so that users can distinguish between product versions using a Major.Minor version number.
  
 
== Revision ==
 
== 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).
+
The revision number is a number starting at 1 and incremented each release.
 +
 
 +
= Artefacts =
  
 
== Files ==
 
== 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.
+
* VERSION.MAJOR
 +
* VERSION.MINOR
 +
* VERSION.REVISION
 +
* VERSION
 +
* RELEASE
 +
 
 +
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 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 time of the last release in the format YEAR-MONTH-DAY-TIME, where YEAR is a four digit year, MONTH a two digit month, DAY a two digit day and TIME is a six digit representation of the 24 hour time the release was made. The RELEASE file is out-of-date after a release is made so it is updated with the content "development" in between releases.
  
 
== Branches ==
 
== 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'.
+
The code for the latest version lives in project/trunk. When a major or minor version is incremented project/trunk is branched into project/branches/version/MAJOR/MINOR for the previous version. So you start work on development version 0.1 and you release it as 0.1.1. You then decide to increment the minor version to 0.2. When this happens the current 0.1 version is branched to project/branches/0/1 then the project/trunk/VERSION.MINOR file is incremented to 2.
  
 
== Tags ==
 
== 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.
+
Tags are created in subversion for each release. For each release there are up to three tags created from the branch being released:
 +
 
 +
* tags/latest (only for releases from trunk)
 +
* tags/version/MAJOR/MINOR
 +
* tags/release/YEAR/MONTH/DAY/TIME.
  
−
== Deprecating major versions ==
+
= Processes =
  
−
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.
+
== Minor upgrade ==
  
−
= Processes =
+
A minor upgrade can only be done on trunk. For a minor upgrade first a branch of trunk to project/branches/MAJOR/MINOR for the current version is done and then the VERSION.MINOR file is incremented and the VERSION file reconstructed.
 +
 
 +
== Major upgrade ==
 +
 
 +
A major upgrade can only be done on trunk. For a major upgrade first a branch of trunk to project/branches/MAJOR/MINOR for the current version is done and then the VERSION.MAJOR file is incremented, the VERSION.MINOR file is reset to '0' and the VERSION file reconstructed.
  
−
== Major release ==
+
== 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.
+
For a release first the RELEASE file is updated with the YEAR-MONTH-DAY-TIME of the release. The VERSION.REVISION file is incremented by 1 and the VERSION file is reconstructed. These changes are committed to the repository. Then the released branch is forked to project/tags/version/MAJOR/MINOR and project/tags/release/YEAR/MONTH/DAY/TIME from either project/trunk or project/branches/MAJOR/MINOR depending on which branch is being released. If the release is from trunk then project/tags/latest is updated too. After the release has been tagged the RELEASE file content is replaced with "development" and committed back to the repository.
  
−
== Minor release ==
+
= References =
  
−
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.
+
* [http://semver.org/ Semantic Versioning]
 +
* [http://en.wikipedia.org/wiki/Versioning Software versioning]

Latest revision as of 15:55, 8 April 2014

This page documents the proposal for a version numbering scheme for all ProgClub projects. This versioning system will be designed and documented here first and implemented for all ProgClub projects when it is ready.

Version numbers will be in the format Major.Minor.Revision as described here. The versioning processes described in this document are to be implemented by the pcsvnrelease script.

Status

This document is a work in progress.

Components

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, i.e. for "political" or "marketing" reasons.

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 so that previous minor versions can go into "maintenance" mode. Generally minor versions are incremented after public or commercial releases of the software so that users can distinguish between product versions using a Major.Minor version number.

Revision

The revision number is a number starting at 1 and incremented each release.

Artefacts

Files

  • VERSION.MAJOR
  • VERSION.MINOR
  • VERSION.REVISION
  • VERSION
  • RELEASE

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 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 time of the last release in the format YEAR-MONTH-DAY-TIME, where YEAR is a four digit year, MONTH a two digit month, DAY a two digit day and TIME is a six digit representation of the 24 hour time the release was made. The RELEASE file is out-of-date after a release is made so it is updated with the content "development" in between releases.

Branches

The code for the latest version lives in project/trunk. When a major or minor version is incremented project/trunk is branched into project/branches/version/MAJOR/MINOR for the previous version. So you start work on development version 0.1 and you release it as 0.1.1. You then decide to increment the minor version to 0.2. When this happens the current 0.1 version is branched to project/branches/0/1 then the project/trunk/VERSION.MINOR file is incremented to 2.

Tags

Tags are created in subversion for each release. For each release there are up to three tags created from the branch being released:

  • tags/latest (only for releases from trunk)
  • tags/version/MAJOR/MINOR
  • tags/release/YEAR/MONTH/DAY/TIME.

Processes

Minor upgrade

A minor upgrade can only be done on trunk. For a minor upgrade first a branch of trunk to project/branches/MAJOR/MINOR for the current version is done and then the VERSION.MINOR file is incremented and the VERSION file reconstructed.

Major upgrade

A major upgrade can only be done on trunk. For a major upgrade first a branch of trunk to project/branches/MAJOR/MINOR for the current version is done and then the VERSION.MAJOR file is incremented, the VERSION.MINOR file is reset to '0' and the VERSION file reconstructed.

Release

For a release first the RELEASE file is updated with the YEAR-MONTH-DAY-TIME of the release. The VERSION.REVISION file is incremented by 1 and the VERSION file is reconstructed. These changes are committed to the repository. Then the released branch is forked to project/tags/version/MAJOR/MINOR and project/tags/release/YEAR/MONTH/DAY/TIME from either project/trunk or project/branches/MAJOR/MINOR depending on which branch is being released. If the release is from trunk then project/tags/latest is updated too. After the release has been tagged the RELEASE file content is replaced with "development" and committed back to the repository.

References

Retrieved from "https://www.progclub.org/wiki/mediawiki/index.php?title=Versions&oldid=3670"