wiki:ReleaseProcedure

Context Navigation

Version 13 (modified by Jari Häkkinen, 17 years ago) ( diff )
Added link to announcement mail

Publishing a release
1. Minor release procedure
  1. Pre-final minor release procedure
  2. Final minor release procedure
2. Patch release procedure

Publishing a release

These instructions cover how to release minor and patch releases in a project that uses trac/subversion for revision control and project management. How to release major releases is not covered yet. Release numbering follows the normal convention of major.minor.patch and the APR (see http://apr.apache.org/versioning.html) guidelines for releases are used.

The main development is performed in the trunk branch of the repository. A new release branch is forked from the trunk for each minor release a short time period before release, and patch releases are snapshots of the minor release branch. This implies that patch work is performed in the minor release branch, and changes made release branch is transferred to the trunk every time a new patch release is made. Remember, patch work should be limited to bug fixes and important fixes only leaving development of new features and designs to the trunk branch, or other special branches.

Releases should only be performed by an appointed member of the team, the Release Manager, and merges should be performed by a Merge Manager. Of course, one team member can be both managers, thus becoming the Release and Merge Manager.

Minor release procedure

This section describes what to do when publishing a minor release. A minor release branch is forked from the trunk when release time is getting closer. After the fork all remaining work for the associated milestone is performed in the minor branch, and if required changes made to the minor branch must be merged into the trunk.

Pre-final minor release procedure

Steps to perform prior to the finalization of the minor release

Make sure that all commits are performed into to the trunk, such as acknowledge contributions (credits.txt ), API changes that may affect backwards compatibility (API changes), and other files as necessary.
Update copyright statements with the below command. Make sure that you do not break file encodings such as UTF-8 and what not. One example, do not use non-US characters for developer names in the source:trunk/.svndigest/config file.
```
./bin/svndigest --copyright --no-report
```
Examine the updates and commit changes with svn ci -m "updating copyright statements". For this step svndigest is obviously needed.

Create the new minor

svn copy http://lev.thep.lu.se/repository/base/trunk \
    http://lev.thep.lu.se/repository/base/branches/A.B-stable \
    -m "Forking new minor version A.B branch"

Prepare the trunk for the next minor release
1. Update version number in source:trunk/build.xml. Locate and change the below line
```
<property name="base.minorversion" value="B+1" />
```
2. Commit changes to the repository, svn ci -m "Changes for future release A.[B+1]"

From now on, all changes needed for the minor release must be done to this new branch only. Changes made are merged into the trunk at release if required

Final minor release procedure

Make sure that all commits are performed into to the minor branch, such as bumping version number(s) (build.xml), acknowledge contributions (credits.txt), API changes that may affect backwards compatibility ([http://base.thep.lu.se/chrome/site/doc/html/appendix/appendix.incompatible.html API changes]), and other files as necessary.
1. Update version number in build.xml. Locate and change the below lines to
```
<property name="base.minorversion" value="B" />
<property name="base.maintenanceversion" value="0" />
```
  That is, make sure that minorversion has value B and that maintenanceversion is 0 (not 0pre).
2. Update credits.txt. Remember, ego and vanity is the currency of open source projects. Well, there are other reasons for open source projects but credits.txt is for boosting peoples' ego.
3. Make sure that the API incompatibility list is up to date API changes. This document should really be changed as the API changes, please do not leave this task to be done at the last minute of release.
4. Make other changes as needed. If items are missing from this list, please add them with proper instructions for the items changes maintenance.
5. Commit changes to the repository, svn ci -m "Preparing release A.B"
Update copyright statements with the below command. Make sure that you do not break file encodings such as UTF-8 and what not. One example, do not use non-US characters for developer names in the .svndigest/config file.
```
./bin/svndigest --copyright --no-report
```
Examine the updates and commit changes with svn ci -m "updating copyright statements". For this step svndigest is obviously needed.
Needless to say, make sure that the program is in a state to be released; make sure that all the tests pass, test the distribution package, and perform all other release tests you think is appropriate:
1. Create an empty test database
2. Setup 'base.config' for the tests.
3. Perform the following sequence of commands
```
ant test
cd build/test
./run.sh TestAll -s
```
  The -s option above will generate less output from the test program.

If you fail in this step, please resolve the issues and restart these procedures.

Create a tag using a one liner like

svn copy http://lev.thep.lu.se/repository/base/branches/A.B-stable \
    http://lev.thep.lu.se/repository/base/tags/A.B \
    -m "Tagging version A.B"

Update the version list in Trac using the trac-admin tool.
Create a distribution package:
```
svn co http://lev.thep.lu.se/repository/base/tags/A.B A.B_dist
cd A.B_dist
ant package
```
Upload the new packages to the download area. Remove A.B_dist directory.
Prepare the minor branch for the first patch release
1. Check out the new minor branch
```
svn co http://lev.thep.lu.se/repository/base/branches/A.B-stable A.B
```
2. Update version number in build.xml. Locate and change the below line
```
<property name="base.maintenanceversion" value="1pre" />
```
3. Commit changes to the repository, svn ci -m "Changes for future release A.B.1"
Update DownloadPage
1. Update the section Latest stable release to reflect the new version, that is
  - Change the version number
  - Update the package links to the new version
2. In section BASE latest release modify the svn command to
```
svn checkout http://lev.thep.lu.se/repository/BASE/tags/A.B base-A.B
```
3. In section BASE stable update link to [milestone:A.B.1 A.B.1] and modify the svn command to
```
svn checkout http://lev.thep.lu.se/repository/base/branches/A.B-stable base-A.B
```
4. In section BASE devel update link to [milestone:A.B+1 A.B+1].
5. Add a Base A.B subsection in the All packaged BASE releases section.
Close the milestone associated with the release and replace head with appropriate revision. Add a new milestone as needed (with an associated log link like Revision Log: log:branches/webservices@3001:head in the description field).
Announce the new release in the mailing list.

Patch release procedure

This section describes what to do when publishing a patch release A.B.C.

Make sure that all commits are performed into to the trunk, such as bumping version number(s) (build.xml), acknowledge contributions (credits.txt), API changes that may affect backwards compatibility (API changes), and other files as necessary.
1. Update version number in build.xml. Locate and change the below line
```
<property name="base.maintenanceversion" value="C" />
```
2. Update credits.txt.
3. Make sure that the API incompatibility list is up to date API changes. This document should really be changed as the API changes, please do not leave this task to be done at the last minute of release.
4. Make other changes as needed. If items are missing from this list, please add them with proper instructions for the items changes maintenance.
5. Commit changes to the repository, svn ci -m "Preparing release A.B.C"
Update copyright statements with the below command. Make sure that you do not break file encodings such as UTF-8 and what not. One example, do not use non-US characters for developer names in the source:trunk/.svndigest/config file.
```
./bin/svndigest --copyright --no-report
```
Examine the updates and commit changes with svn ci -m "updating copyright statements". For this step svndigest is obviously needed.
Needless to say, make sure that the program is in a state to be released; make sure that all the tests pass, test the distribution package, and perform all other release tests you think is appropriate:
```
Please add test command sequence here
```
If you fail in this step, please resolve the issues and restart these procedures.