[[PageOutline(1-3,Contents,inline)]]

= 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.

Currently, Nicklas Nordborg is the Release Manager and Merge Master.


== 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
 1. Make sure that all commits are performed into to the trunk, such
    as acknowledge contributions ([source:trunk/credits.txt 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.
    [[br]][[br]]
 1. 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.
{{{
svndigest --copyright --no-report
}}}
    Examine the updates and commit changes with
    `svn ci -m "updating copyright statements"`. For this step
    [http://trac.thep.lu.se/svndigest svndigest] is obviously
    needed. [[br]][[br]]
 1. Create the new minor
{{{
svn copy http://base.thep.lu.se/svn/trunk \
    http://base.thep.lu.se/svn/branches/A.B-stable \
    -m "Forking new minor version A.B branch"
}}}
 1. Prepare the trunk for the next minor release [[br]][[br]]
  i. Update version number in source:trunk/build.xml. Locate and
     change the below line
{{{
<property name="base.minorversion" value="[B+1]" />
}}}
  i. Commit changes to the repository,
     `svn ci -m "Changes for future release A.[B+1]"` [[br]][[br]]

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 ===
 1. 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. [[br]][[br]]
  i. 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''). [[br]][[br]]
  i. 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. [[br]][[br]]
  i. Make sure that the API incompatibility list is up to date
     [http://base.thep.lu.se/chrome/site/doc/html/appendix/appendix.incompatible.html 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. [[br]][[br]]
  i. Make other changes as needed. If items are missing from this list, please add them with proper
     instructions for the items changes maintenance. [[br]][[br]]
  i. Commit changes to the repository, `svn ci -m "Preparing release A.B"`
     [[br]][[br]]
 1. 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.
{{{
svndigest --copyright --no-report
}}}
    Examine the updates and commit changes with `svn ci -m "updating copyright statements"`. For
    this step [http://trac.thep.lu.se/svndigest svndigest] is obviously needed. [[br]][[br]]
 1. 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. ''If you fail in this step, please resolve the issues and restart these procedures.''
  i. Create an empty test database
  i. Setup 'base.config' for the tests.
  i. 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. [[br]][[br]]
 1. Create a tag using a one liner like
{{{
svn copy http://base.thep.lu.se/svn/branches/A.B-stable \
    http://base.thep.lu.se/svn/tags/A.B \
    -m "Tagging version A.B"
}}}
 1. Update the version list in Trac using the
    [http://base.thep.lu.se/admin/ticket/versions trac-admin tool].
    [[br]][[br]]
 1. Create the distribution package:
{{{
svn co http://base.thep.lu.se/svn/tags/A.B A.B_dist
cd A.B_dist
ant package
}}}
    Upload the new files to the [http://base2.thep.lu.se/base/ download area].
    Remove `A.B_dist` directory.[[br]][[br]]
    Create a new subdirectory `A.B.0` in [http://base2.thep.lu.se/base/jars]. Upload
    the BASE2*.jar files to the subdirectory. [[br]][[br]]
 1. Prepare the minor branch for the first patch release [[br]][[br]]
  i. Check out the new minor branch
{{{
svn co http://base.thep.lu.se/svn/branches/A.B-stable A.B
}}}
  i. Update version number in `build.xml`. Locate and change the
     below line
{{{
<property name="base.maintenanceversion" value="1pre" />
}}}
  i. Commit changes to the repository,
     `svn ci -m "Changes for future release A.B.1"` [[br]][[br]]
 1. Update DownloadPage [[br]][[br]]
  i. Update the section '''Latest stable release''' to reflect the new
     version, that is [[br]][[br]]
   * Change the version number [[br]][[br]]
   * Update the package links to the new version [[br]][[br]]
  i. In section '''BASE ''latest release'' ''' modify the svn command to
{{{
svn checkout http://base.thep.lu.se/svn/tags/A.B base-A.B
}}}
  i. In section '''BASE ''stable'' ''' update link to
     `[milestone:A.B.1 A.B.1]` and modify the svn command to
{{{
svn checkout http://base.thep.lu.se/svn/branches/A.B-stable base-A.B
}}}
  i. In section '''BASE ''devel'' ''' update link to `[milestone:A.B+1 A.B+1]`.[[br]][[br]]
  i. Add a ''Base A.B'' subsection in the '''All packaged BASE releases''' section. [[br]][[br]]
 1. Check out the new branch for online documentation use, generate documentation, and change the symbolic link on the trac server to point to the latest stable release
{{{
ssh tracuser@base.thep.lu.se
cd /path/to/base/trac
svn co http://lev.thep.lu.se/repository/branches/A.B-stable base-A.B
cd base-A.B
ant doc
cd ..
rm base-latest
ln -s base-A.B base-latest
}}}
 1. If required, merge the patch release into the trunk. To avoid
    confusion and minimize the risk of loosing fixes, this step is
    only performed by the Merge Master. [[br]][[br]]
  i. Checkout a pristine version of the trunk.
{{{
svn checkout http://base.thep.lu.se/svn/trunk trunk_merge
}}}
  i. Merge changes into trunk. In this example the difference between
     minor branch at forking time and the minor release tag is merged
     into the trunk WC
{{{
cd trunk_merge
svn merge http://base.thep.lu.se/svn/branches/A.B-stable@fork_revision \
          http://base.thep.lu.se/svn/tags/A.B
}}}
  i. Resolve all conflicts. Run tests and perform all other
     appropriate tests to make sure that the merge does not create
     havoc. (run !TestAll and perform an installation.) [[br]][[br]]
  i. Commit changes to the trunk branch.
{{{
svn commit -m "Merged pre-A.B-releases to the trunk. Delta A.B - A.B@fork_revision"
}}}
 1.  ''Performing this step is to acknowledge that the merge has been performed.'' [[br]]
    Close the [http://base.thep.lu.se/roadmap 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). [[br]][[br]]
 1. [mailto:basedb-users@lists.sourceforge.net,basedb-devel@lists.sourceforge.net,basedb-announce@lists.sourceforge.net 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.

 1. Make sure that all commits are performed into to the branch, such
    as bumping version number(s) ([source:trunk/build.xml build.xml]),
    acknowledge contributions ([source:trunk/credits.txt 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.
    [[br]][[br]]
  i. Update version number in `build.xml`. Locate and change the
     below line
{{{
<property name="base.maintenanceversion" value="C" />
}}}
  i. Update `credits.txt`. [[br]][[br]]
  i. Make sure that the API incompatibility list is up to date
     [http://base.thep.lu.se/chrome/site/doc/html/appendix/appendix.incompatible.html 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. [[br]][[br]]
  i. Make other changes as needed. If items are missing from this list, please add them with proper
     instructions for the items changes maintenance. [[br]][[br]]
  i. Commit changes to the repository, `svn ci -m "Preparing release A.B.C"`
     [[br]][[br]]
 1. 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. ''If you fail in this step, please resolve the issues and restart these procedures.''
  i. Create an empty test database
  i. Setup 'base.config' for the tests.
  i. 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. [[br]][[br]]
 1. Create a tag using a one liner like
{{{
svn copy http://base.thep.lu.se/svn/branches/A.B-stable \
    http://base.thep.lu.se/svn/tags/A.B.C \
    -m "Tagging version A.B.C"
}}}
 1. Update the version list in Trac using the
    [http://base.thep.lu.se/admin/ticket/versions trac-admin tool].
    [[br]][[br]]
 1. Create the distribution package:
{{{
svn co http://base.thep.lu.se/svn/tags/A.B.C A.B.C_dist
cd A.B.C_dist
ant package
}}}
    Upload the new files to the [http://base2.thep.lu.se/base/ download area].
    Remove `A.B.C_dist` directory. [[br]][[br]]
    Create a new subdirectory A.B.C in [http://base2.thep.lu.se/base/jars]. Upload
    the BASE2*.jar files to the subdirectory. [[br]][[br]]
 1. Prepare the minor branch for the next patch release [[br]][[br]]
  i. Update version number in `build.xml`. Locate and change the
     below line
{{{
<property name="base.maintenanceversion" value="[C+1]pre" />
}}}
  i. Commit changes to the repository,
     `svn ci -m "Changes for future release A.B.[C+1]"` [[br]][[br]]
 1. Update DownloadPage [[br]][[br]]
  i. Update the section '''Latest stable release''' to reflect the new
     version, that is [[br]][[br]]
   * Change the version number [[br]][[br]]
   * Update the package links to the new version [[br]][[br]]
  i. In section '''base ''latest release'' ''' modify the svn command to
{{{
svn checkout http://base.thep.lu.se/svn/tags/A.B.C base-A.B.C
}}}
  i. In section '''base ''stable'' ''' update link to
     `[milestone:A.B.[C+1] A.B.[C+1]]`.[[br]][[br]]
  i. Add a new entry to the ''Base A.B'' subsection in the '''All packaged BASE releases'''
     section. [[br]][[br]]
 1. Close the milestone associated with the release and replace `head` with appropriate
    revision in log link. Add a new milestone as needed (with an associated log link like
    ''Revision Log: log:branches/A.B-stable@3001:head'' in the description field). [[br]][[br]]
 1. [mailto:basedb-users@lists.sourceforge.net,basedb-devel@lists.sourceforge.net,basedb-announce@lists.sourceforge.net Announce]
    the new release in the mailing list.[[br]][[br]]
 1. Merge the patch release into the trunk. To avoid confusion and
    minimize the risk of loosing fixes, this step is only performed by
    the Merge Master. [[br]][[br]]
  i. Checkout a pristine version of the trunk.
{{{
svn checkout http://base.thep.lu.se/svn/trunk trunk_merge
}}}
  i. Merge changes into trunk. In this example the difference between a
     minor release tag and the first patch release tag is merged into
     the trunk WC
{{{
cd trunk_merge
svn merge http://base.thep.lu.se/svn/tags/A.B.[C-1] \
          http://base.thep.lu.se/svn/tags/A.B.C
}}}
  i. Resolve all conflicts. Run tests and perform all other
     appropriate tests to make sure that the merge does not create
     havoc. (run !TestAll and perform an installation.) [[br]][[br]]
  i. Commit changes to the trunk branch.
{{{
svn commit -m "Merged patch release A.B.C to the trunk. Delta A.B.C - A.B.[C-1]"
}}}