[[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 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, 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.
1. Make sure that all commits are performed into to the trunk, 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 [source:trunk/build.xml build.xml]. Locate and change the
below line
{{{
}}}
i. Update [source:trunk/credits.txt credits.txt]. Remember, ego and vanity is the currency of open
source projects. Well, there are other reasons for open source
projects but [source:trunk/credits.txt 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
{{{
./bin/svndigest --copyright
}}}
Examine the updates and commit changes with `svn ci -m "updating copyright statements"`. For
this step [http://trac.thep.lu.se/trac/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:
{{{
Please add test command sequence here
}}}
If you fail in this step, please resolve the issues and restart these procedures. [[br]][[br]]
1. Create a tag using a one liner like
{{{
svn copy http://lev.thep.lu.se/repository/base/trunk \
http://lev.thep.lu.se/repository/base/tags/A.B \
-m "Tagging version A.B"
}}}
1. Update the version list in Trac using the
[http://base.thep.lu.se/admin trac-admin tool].
[[br]][[br]]
1. 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 are (Currently `~jari/www/base` directory).
Remove `A.B_dist` directory. [[br]][[br]]
1. Create a new minor branch using a one liner like
{{{
svn copy http://lev.thep.lu.se/repository/base/tags/A.B \
http://lev.thep.lu.se/repository/base/branches/A.B-stable \
-m "New minor version A.B branch"
}}}
Prepare the minor branch for the first patch release [[br]][[br]]
i. Check out the new minor branch
{{{
svn co http://lev.thep.lu.se/repository/base/branches/A.B-stable A.B
}}}
i. Update version number in `build.xml`. Locate and change to the
below line
{{{
}}}
i. Commit changes to the repository,
`svn ci -m "Changes for future release A.B.1"` [[br]][[br]]
1. Prepare the trunk for the next minor release [[br]][[br]]
i. Update version number in `build.xml`. Locate and change the
below line
{{{
}}}
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://lev.thep.lu.se/repository/BASE/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://lev.thep.lu.se/repository/base/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. Close the [http://trac.thep.lu.se/trac/svndigest/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).
== 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 version number in `configure.ac`. Locate and change the
below line
{{{
AC_INIT([svndigest],[A.B.C],[jari.at.thep.lu.se])
}}}
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://trac.thep.lu.se/trac/svndigest/log/branches/A.B-stable?rev=N&stop_rev=M
- http://trac.thep.lu.se/trac/svndigest/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 commands
{{{
./bootstrap
make all
make check
./bin/svndigest --copyright
}}}
Examine the updates and commit changes with `svn ci -m "updating copyright statements"`.[[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:
{{{
./bootstrap
make check
make distcheck
}}}
1. Create a tag using a one liner like
{{{
svn copy http://lev.thep.lu.se/repository/svndigest/branches/A.B-stable \
http://lev.thep.lu.se/repository/svndigest/tags/A.B.C \
-m "Tagging version A.B.C"
}}}
1. Update the version list in Trac using the
[http://lev.thep.lu.se/trac/svndigest/admin trac-admin tool].
[[br]][[br]]
1. Create a distribution package:
{{{
svn co http://lev.thep.lu.se/repository/svndigest/tags/A.B.C A.B.C_dist
cd A.B.C_dist
./bootstrap
./configure [OPTION]...
make dist
}}}
Attach the new package to the DownloadPage. Remove `A.B.C_dist`
directory. [[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 '''svndigest ''latest release'' ''' update link to
`[source:tags/A.B.C/NEWS NEWS]` and modify the svn command to
{{{
svn checkout http://lev.thep.lu.se/repository/svndigest/tags/A.B.C svndigest-A.B.C
}}}
i. In section '''svndigest ''stable'' ''' update link to
`[milestone:A.B.[C+1] A.B.[C+1]]`.[[br]][[br]]
i. On WikiStart update links `[source:tags/A.B/doc/readme.txt Manual]`, `[source:tags/A.B/NEWS NEWS]`, and `[source:tags/A.B/INSTALL Install]`, .[[br]][[br]]
1. Prepare the minor branch for the next patch release [[br]][[br]]
i. Update version number in `configure.ac`. Locate and change the
below line
{{{
AC_INIT([svndigest],[preA.B.[C+1]],[jari.at.thep.lu.se])
}}}
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://trac.thep.lu.se/trac/svndigest/log/branches/A.B-stable?rev=HEAD&stop_rev=[M+1]
- http://trac.thep.lu.se/trac/svndigest/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. Checkout a pristine version of the trunk.
{{{
svn checkout http://lev.thep.lu.se/repository/svndigest/trunk 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
{{{
cd trunk_merge
svn merge http://lev.thep.lu.se/repository/svndigest/tags/A.B \
http://lev.thep.lu.se/repository/svndigest/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. [[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"
}}}
1. Close the milestone associated with the release and replace `head` with appropriate revision in log link. Add a new
milestone as needed (with a log link).