How to tag releases of GenABEL suite packages

by Lennart Karssen

Creating tags

I recently added a branches and a tags directory to the SVN repo. So far I've added a tag for GenABEL v1.6-7 and ProbABEL-0.1-9e, based on the SVN logs.

Maintainers of packages (with commit rights to the SVN repo) should remember to make a tag when they release a new version of their package. This way we can always go back to a specific release (e.g. to backport bug fixes). A tag is created like this:

$ svn copy -r 729 \
     svn+ssh://committer-name@svn.r-forge.r-project.org/svnroot/genabel/pkg/GenABEL \
     svn+ssh://committer-name@svn.r-forge.r-project.org/svnroot/genabel/tags/GenABEL/v.1.6-7 \
     -m "Tagging release 1.6-7 of GenABEL."

where the number 729 indicates the SVN revision that contains the released version. If no changes were committed to SVN since the release the ''-r <number>'' is unnecessary. The ''<committer-name>'' is the name of your R-forge account.

Creating branches

If you plan to make major changes to the code, especially if you think the development process will take a long time it is best to create a so-called branch. There you can work for as long as you want and change as much as you want without hindering the developments in the main svn directory (''pkg'' and its subdirectories). To create a branch first check out the latest versions from SVN (see this tutorial for more information). Go into that directory and into the ''branches'' directory. There you create a subdirectory with a descriptive name. Then you add the directory to SVN and commit.

$ cd branches
$ mkdir GenABEL-branch-for-amazing-new-feature
$ snv add GenABEL-branch-for-amazing-new-feature
$ svn commit GenABEL-branch-for-amazing-new-feature \
 -m "Added directory for the branch for a new feature of GenABEL."

Now you can do the actual branching in the following way (notice the similarities with the tag command above):

$ svn copy \
     svn+ssh://committer-name@svn.r-forge.r-project.org/svnroot/genabel/pkg/GenABEL \
     svn+ssh://committer-name@svn.r-forge.r-project.org/svnroot/genabel/branches/GenABEL-branch-for-amazing-new-feature/ \
     -m "Creating actual branch for new feature in GenABEL."

The ''<committer-name>'' is the name of your R-forge account.

While working on your new feature you can use ''svn commit'' etc. as usual to track you changes. Be sure to keep your branch also updated with the changes in trunk. See the SVN manual for details on how to do this. In its simplest form it's a matter of:

  $ svn merge -r XXX:YYY ^/pkg/YOURPACKAGE

Here XXX is either the revision number when you started the branch or the revision number of your last merge. To find the revision number "at branch time" go into the branch directory and run the following to find all log messages with the word branch:

$ svn log | grep -C3 branch

YYY is the revision number of trunk (often the latest revision number). The ^ is a shorthand for the base URL of the repository. Once you are satisfied with your changes (and you have verified that they work as expected) you can merge your work with the main development branch (usually called trunk) in the ''pkg'' directory. Since this can cause a lot of trouble and because it is a good idea to discuss large changesets on the mailing list before merging them back into trunk I will not go into details on how to do that here, but in short this is the procedure:

$ cd pkg/YOURPACKAGE      # This is the trunk of your package
$ svn merge -r XXX:YYY ^/branches/YOURBRANCH

Here, XXX and YYY are defined as above. Currently, svn merge --reintegrate doesn't work on R-forge, because the repositories haven't been updated to the latest version of Subversion.

Help

If part of these processes is unclear, don't hesitate to send a mail to the list. The SVN manual has a much more detailed description on tags and branches.