[[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 since we
have not done that (with the exception of the first release). 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 created for each minor release
from the trunk 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.

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.

=== Creating a release branch ===

Once people agree that a new release branch should be made, the ''Release Manager'' creates it with the following procedure (substitute A.B with the version you are preparing, ''e.g.'' 0.3, or 1.0): 

 1. Update copyright statements with command:
{{{
svndigest --copyright --no-report -v
}}}
 (The `--no-report` option works with svndigest 0.7 and later, for earlier version omit the option.) Examine the updates and commit changes with `svn ci -m "updating copyright statements"`.
 For this step [http://dev.thep.lu.se/svndigest svndigest] is obviously needed.[[br]][[br]]
 1. Create a new minor branch using a one liner like
{{{
svn copy http://dev.thep.lu.se/yat/svn/trunk \
    http://dev.thep.lu.se/yat/svn/branches/A.B-stable \
    -m "New minor version A.B branch"
}}}
 1. Prepare the trunk for the next minor release [[br]][[br]]
  i. Update version number in `build_support/version.m4`. Locate and change the
     below line
{{{
m4_define([MINOR_VERSION], [B+1])
}}}
  i. Add an entry in `NEWS`
{{{
version A.[B+1] (released DATE)
}}}
     The date is set when version A.[B+1] is released. [[br]][[br]]
  i. Add an entry in `ChangeLog`
{{{
version A.[B+1]:
	- http://dev.thep.lu.se/yat/log/branches/A.B-stable?rev=HEAD&stop_rev=M+1
	- http://dev.thep.lu.se/yat/query?milestone=A.[B+1]&order=id
}}}
  i. Commit changes to the repository,
     `svn ci -m "Changes for future release A.[B+1]"` [[br]][[br]]

=== Rolling a minor release ===

 1. Make sure that all commits are performed into the minor branch, such
    as bumping version number(s) (`version.m4`),
    acknowledge contributions (`THANKS`), update
    files `NEWS` and `ChangeLog`.
    [[br]][[br]]
  i. Update version number in `build_support/version.m4`. Locate and change the
     below line
{{{
m4_define([DEV_BUILD], [false])
}}}
  i. Update the interface version number in `build_support/version.m4`. Locate and set the version in the
     below line
{{{
m4_define([YAT_LT_CURRENT], [c])
m4_define([YAT_LT_REVISION], [r])
m4_define([YAT_LT_AGE], [a])
}}}
     appropriately. Refer to the interface version list in `build_support/version.m4` to figure out the settings of c, r, and a. c should increase with 1 if the interface has changed. If the interface is changed, r should be set to zero and a should be set to reflect backward compatibility level of this version. If interface was not changed just increase r with 1. See `build_support/version.m4` and the [http://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning libtool manual] for details.[[br]][[br]]
  i. Update `THANKS`. Remember, ego and vanity is the currency of open
     source projects. Well, there are other reasons for open source
     projects but `THANKS` is for boosting people's ego. [[br]][[br]]
  i. Set the date for the new release in `NEWS`.
{{{
version A.B (released 26 June 2007)
}}}
    Make sure that the items in `NEWS` cover the new features of the
    release. [[br]][[br]]
  i. Finalize the links to trac in `ChangeLog`
{{{
version A.B:
        - http://dev.thep.lu.se/yat/log/branches/0.6-stable?action=stop_on_copy&rev=N&stop_rev=M&mode=follow_copy
	- http://dev.thep.lu.se/yat/query?milestone=A.B&order=id
}}}
     where M should be current HEAD+2 (2 more commits are needed before release),
     and N should have been set at previous minor release.
     [[br]][[br]]
  i. Commit changes to the repository, `svn ci -m "Preparing release A.B"`
     [[br]][[br]]
 1. Update copyright statements with command:
{{{
svndigest --copyright --no-report -v
}}}
 Examine the updates and commit changes with `svn ci -m "updating copyright statements"`.
 For this step [http://dev.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:[[br]][[br]]
    Remove all unversioned files using
{{{
make svn-clean
}}}
    Check that remove was complete and that wc is up to date
{{{
svn status -u
}}}
    which should display nothing. Build and test the package 
{{{
./bootstrap && ./configure && make distcheck
}}}
    If everything is ok, attach the new package to the DownloadPage, else start over.[[br]][[br]]
 1. Create a tag, but first check that you are synchronized with repository
{{{
svn status -q -u
}}}
 and then create a tag using a one liner like
{{{
svn copy http://dev.thep.lu.se/yat/svn/branches/A.B-stable \
    http://dev.thep.lu.se/yat/svn/tags/A.B \
    -m "Tagging version A.B"
}}}
 1. Update the version list in Trac using the
    [http://dev.thep.lu.se/yat/admin/ticket/versions trac-admin tool].
    Remember to set the date.[[br]][[br]]
 1. Prepare the minor branch for the first patch release [[br]][[br]]
  i. Update version number in `build_support/version.m4`. Locate and change the
     below lines
{{{
m4_define([PATCH_VERSION], [1])
m4_define([DEV_BUILD], [true])
}}}
  i. Add an entry in `NEWS`
{{{
version A.B.1 (released DATE)
}}}
     The date is set when version A.B.1 is released. [[br]][[br]]
  i. Add an entry in `ChangeLog`
{{{
version A.B.1:
	- http://dev.thep.lu.se/yat/log/trunk?rev=[M+1]&stop_rev=HEAD
	- http://dev.thep.lu.se/yat/query?milestone=A.B.1&order=id
}}}
  i. Commit changes to the repository,
     `svn ci -m "Changes for future release A.B.1"` [[br]][[br]]
 1. Update DownloadPage and [wiki:WikiStart WikiStart][[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 link to the new version [[br]][[br]]
   * Update link to NEWS file to `source:tags/A.B/NEWS` [[br]][[br]]
  i. In section '''yat ''latest release'' ''' update link to
     `[source:tags/A.B/NEWS NEWS]` and modify the svn commands to
{{{
svn checkout http://dev.thep.lu.se/yat/svn/tags/A.B yat-A.B
}}}
{{{
svn switch http://dev.thep.lu.se/yat/svn/tags/A.B
}}}
  i. In section '''yat ''stable'' ''' update link to
     `[milestone:A.B.1 A.B.1]` and modify the two svn commands to
{{{
svn checkout http://dev.thep.lu.se/yat/svn/branches/A.B-stable yat-A.Bdev
}}}
{{{
svn switch http://dev.thep.lu.se/yat/svn/branches/A.B-stable
}}}
  i. In section '''yat ''devel'' ''' update link to `[milestone:A.B+1 A.B+1]`.[[br]][[br]]
  i. On WikiStart update links `[source:tags/A.B/NEWS NEWS]`.[[br]][[br]] 
  i. Generate documentation to new version of yat, and update link on WikiStart.[[br]][[br]]
 1. If required, merge the minor 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. Switch to the trunk or checkout a pristine version of the trunk.
{{{
svn switch http://dev.thep.lu.se/yat/svn/trunk

}}}
     or
{{{
svn checkout http://dev.thep.lu.se/yat/svn/trunk trunk_merge
cd 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
{{{
svn merge http://dev.thep.lu.se/yat/svn/branches/A.B-stable@fork_revision \
          http://dev.thep.lu.se/yat/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. Typically changes in `build_support/version.m4` are problematic
     so check this file extra carefully.[[br]][[br]]
  i. Commit changes to the trunk branch.
{{{
svn commit -m "Merged patch release A.B to the trunk. Delta A.B - A.B@fork_revision"
}}}
    Remove `trunk_merge` if it was created. [[br]][[br]]
 1. Close the [http://dev.thep.lu.se/yat/roadmap milestone]
    associated with the release and replace `head` with appropriate revision. Add a new milestone as needed (with log link).


== 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) (`configure.ac`), acknowledge
    contributions (`THANKS`), update files `NEWS` and
    `ChangeLog`. [[br]][[br]]
  i. Update the release version number in `build_support/version.m4`. Locate and change the
     below line
{{{
m4_define([DEV_BUILD], [false])
}}}
  i. Update `THANKS`. [[br]][[br]]
  i. Set the date for the new release in `NEWS`
{{{
version A.B.C (released 27 June 2007)
}}}
    Make sure that the items in `NEWS` cover all important bug fixes of the
    release. [[br]][[br]]
  i. Finalize the links to trac in `ChangeLog`
{{{
version A.B.C:
	- http://dev.thep.lu.se/yat/log/branches/A.B-stable?rev=N&stop_rev=M
	- http://dev.thep.lu.se/yat/query?milestone=A.B.C&order=id
}}}
  where `N` is given by 
{{{
$ svn update
N-2
}}}
  and `M` should have been set at previous release.[[br]][[br]]
  i. Commit changes to the repository, `svn ci -m "Preparing release A.B.C"`
     [[br]][[br]]
 1. Update copyright statements with command:
{{{
svndigest --copyright --no-report
}}}
 Examine the updates and commit changes with `svn ci -m "updating copyright statements"`.
 For this step [http://dev.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:[[br]][[br]]
    Remove all unversioned files using
{{{
make svn-clean
}}}
    Check that remove was complete and that wc is up to date
{{{
svn status -u
}}}
    which should display nothing. Build and test the package 
{{{
./bootstrap && ./configure && make distcheck
}}}
    If everything is ok, attach the new package to the DownloadPage, else start over.[[br]][[br]]
 1. Create a tag, but first check that you are synchronized with repository
{{{
svn status -q -u
}}}
 and then create a tag using a one liner like
{{{
svn copy http://dev.thep.lu.se/yat/svn/branches/A.B-stable \
    http://dev.thep.lu.se/yat/svn/tags/A.B.C \
    -m "Tagging version A.B.C"
}}}
 1. Update the version list in Trac using the
    [http://dev.thep.lu.se/yat/admin/ticket/versions trac-admin tool].
    Remember to set the date.[[br]][[br]]
 1. Update DownloadPage and [wiki:WikiStart WikiStart][[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 link to the new version [[br]][[br]]
   * Update link to NEWS file to `source:tags/A.B.C/NEWS` [[br]][[br]]
  i. In section '''yat ''latest release'' ''' update link to
     `[source:tags/A.B.C/NEWS NEWS]` and modify the svn commands to
{{{
svn checkout http://dev.thep.lu.se/yat/svn/tags/A.B.C yat-A.B.C
}}}
{{{
svn switch http://dev.thep.lu.se/yat/svn/tags/A.B.C
}}}
  i. In section '''yat ''stable'' ''' update link to
     `[milestone:A.B.[C+1] A.B.[C+1]]`.[[br]][[br]]
  i. On WikiStart update reference to explicit latest version number, and `[source:tags/A.B/NEWS NEWS]`.[[br]][[br]] 
  i. Generate documentation to new version of yat, and update link on WikiStart.[[br]][[br]]
 1. Prepare the minor branch for the next patch release [[br]][[br]]
  i. Update version number in `build_support/version.m4`. Locate and change the
     below lines
{{{
m4_define([PATCH_VERSION], [C+1])
m4_define([DEV_BUILD], [true])
}}}
  i. Update the interface version number in `build_support/version.m4`. Locate and change the
     below line
{{{
m4_define([YAT_LT_REVISION], [r+1])
}}}
     i.e., only raise the revision number since the interface was not changed. See the [http://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning libtool manual] for details.[[br]][[br]]
  i. Add an entry in `NEWS`
{{{
version A.B.[C+1] (released DATE)
}}}
     The date is set when version A.B.[C+1] is released. [[br]][[br]]
  i. Add an entry in `ChangeLog`
{{{
version A.B.[C+1]:
	- http://dev.thep.lu.se/yat/log/branches/A.B-stable?rev=HEAD&stop_rev=[M+1]
	- http://dev.thep.lu.se/yat/query?milestone=A.B.[C+1]&order=id
}}}
  i. Commit changes to the repository,
     `svn ci -m "Changes for future release A.B.[C+1]"` [[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. Switch to the trunk or checkout a pristine version of the trunk.
{{{
svn switch http://dev.thep.lu.se/yat/svn/trunk
}}}
     or
{{{
svn checkout http://dev.thep.lu.se/yat/svn/trunk trunk_merge
cd trunk_merge
}}}
  i. Merge changes into trunk. In this example the diffence between a
     minor release tag and the first patch release tag is merged into
     the trunk WC
{{{
svn merge http://dev.thep.lu.se/yat/svn/tags/A.B \
          http://dev.thep.lu.se/yat/svn/tags/A.B.1
}}}
  i. Resolve all conflicts. Run tests and perform all other
     appropriate tests to make sure that the merge does not create
     havoc. Typically changes in `build_support/version.m4` are problematic
     so check this file extra carefully.[[br]][[br]]
  i. Commit changes to the trunk branch.
{{{
svn commit -m "Merged patch release A.B.1 to the trunk. Delta A.B.1 - A.B"
}}}
    Remove `trunk_merge` if it was created. [[br]][[br]]
 1. Close the milestone associated with the release, replace `head` with appropriate revision in log link, 
    set diff to '`diff:tags/A.B.[C-1]//tags/A.B.C/`'. Create a log link, '`log:branches/A.B-stable@TAG-REVISION:head`', 
    and diff, '`diff:tags/A.B.C//branches/A.B-stable/`', in milestone associated with next patch release.