Versioning and Releasing Software¶
| Status: | 2010-10-24 Draft for review |
|---|
Performing a formal release of software provides a well defined basis for comparison and building upon as opposed to the alternative which is the ad-hoc arrangements and editing of source. The later may work well in highly experimental situations where a general structure is being worked out, but leads to many problems as the project becomes more complex and involves several components.
The DataONE infrastructure can be divided into a number of reasonably segregated chunks of functionality, and these chunks are being labelled as “products” that should follow a well defined and consistent process for their release (internal to the project or otherwise). By doing so, we provide a consistent basis upon which dependent functionality may be developed, and thus reduce the potential for confusion and thrashing when source that has many dependents is modified.
This document outlines the procedure for releasing a component in the DataONE development process.
General Process¶
Figure 1 shows a generic example of the process being followed for a product release. In this examples, revisions 1 through 100 are used to get the product to a point where it is deemed acceptable for release. The tests are passing and the functionality being expressed is as desired. An “alpha” release of the product is made by creating a release branch and a corresponding tag using the svn copy operations on the trunk.
Figure 1. Ficticious subversion graph for the release of a product.
Subsequent testing reveals a bug, which is corrected and committed to the branch at revision 103. To help minimize problems encountered when merging a developing trunk and branch, the bug is also merged with the trunk immediately. After this (or more likely several other) bug fixes, the product is deemed to be at the “beta” release stage, and is tagged as such then exposed to a broader test audience. Additional bugs are found and the same process for the alpha bug fixes is followed until the product is deemed ready for release, at which point the release tag is created.
Development continues on the trunk, building towards the next release. At the same time, minor changes and bug fixes are made on the release branch, eventually resulting in a new minor release. At this stage, the bug fix is merged back into the trunk depending on changes to the trunk code, this may be a somewhat tedious process (revision 122). The release tag is updated to indicate the new release version.
Throughout this process, there are five basic actions being performed on subversion:
- Create a release branch
- Perform pre-release corrections
- Create a release tag
- Post-release fixes and tagging
- Merging release branch updates with the development trunk
These are outlined in more detail below using the fictitious product “widget” which is managed in the subversion repository http://widgets.r.us/svn/widget which has trunk, tags, and branches within the widget folder.
Release Names¶
Release names include a combination of the product name, the version number and an optional qualifier with the general pattern of:
product_name_<major>_<minor>_<micro>[_<qualifier>]
The qualifier can be “alpha”, “beta” or “rc-x” where x indicates the sequence number of a release candidate (with “1” being the first one).
The version numbers are of the form x.y.z or <major>.<minor>.<micro>. The <major> version number is only increased when a significant amount of new functionality is added to the product. The <minor> version number is only increased when some functionality is added to the new release, in which case the new release version number will be x.(y+1).0. When only bugfixes are part of the new release there will be a so-called point release. The version number of the new release in this case will be x.y.(z+1).
Creating a Release Branch¶
This is performed using the svn copy command. The release is version 0.1.0-alpha. Note that the tag is made from the branch copy to ensure that the release tag corresponds exactly with the branch:
# create the branch
svn copy http://widgets.r.us/svn/widget/trunk \
http://widgets.r.us/svn/widget/branches/widget-v0.1 \
-m "Creating the 0.1 release branch for widget"
# tag the initial release
svn copy http://widgets.r.us/svn/widget/branches/widget-v0.1 \
http://widgets.r.us/svn/widget/tags/widget-v0.1.0-alpha \
-m "Creating the 0.1.0-alpha release tag for widget"
# check out a copy of the release branch for bug fixes
svn co http://widgets.r.us/svn/widget/branches/widget-v0.1
Performing Pre-release Corrections¶
# Commit the updates to the branch from the release working copy
cd widget-v0.1
svn commit -m "Bug fix ... "
# Move to the trunk working copy
cd ../widget
svn update
# Merge the changes into the HEAD of the trunk working copy
svn merge http://widgets.r.us/svn/widget/branches/widget-v0.1 .
# Edit if necessary to resolve conflicts
# Commit the merged results
svn commit -m "Merging bug fixes from v0.1 back into trunk"
Creating a Release Tag¶
svn copy http://widgets.r.us/svn/widget/branches/widget-v0.1 \
http://widgets.r.us/svn/widget/tags/widget-v0.1.0-beta \
-m "Creating the 0.1.0-beta release tag for widget"
Post-release Fixes and Tagging¶
# Commit the bug fixes from the branch
cd widget-v0.1
svn commit -m "Bug fixes ..."
# Tag the new release
svn copy http://widgets.r.us/svn/widget/branches/widget-v0.1 \
http://widgets.r.us/svn/widget/tags/widget-v0.1.1 \
-m "Creating the 0.1.1 release tag for widget"
# Merge the changes into the HEAD of the trunk working copy
cd <<to location of product in trunk>>
svn merge http://widgets.r.us/svn/widget/branches/widget-v0.1 .
# Edit if necessary to resolve conflicts
# Commit the merged results
svn commit -m "Merging bug fixes from v0.1 back into trunk"
Merging Two Development Streams¶
# Merge the changes into the HEAD of the trunk working copy
cd <<to location of product in trunk>>
svn merge http://widgets.r.us/svn/widget/branches/widget-v0.1 .
# Edit if necessary to resolve conflicts
# Commit the merged results
svn commit -m "Merging bug fixes from v0.1 back into trunk"