Patch Release Strategy - The Gory Details

Peter Briggs 18th March 2002

Introduction and Overview

This is a detailed look at how we will provide patches for the suite post-4.2. My plan is simple:

  1. Release 4.2 as source and binaries
  2. Fix bugs, then release 4.2.1. Also provide source code patch for going from 4.2 to 4.2.1. Update the binaries.
  3. Repeat 2) for 4.2.1 to 4.2.2 etc etc until next major release.

The aim of this document is to figure out exactly how this will work.

Contents:

Useful link: CVS manual

1. Developer Side

1.1 Overview

This is how I imagine it working on the developer side:

  1. Immediately after release of 4.2 split off a patch branch in CVS
  2. All bug fixes are made to the patch branch, and to main developmental branch if relevant
  3. Fixes are reported on the problems page
  4. After a certain period of time patch release is made from the patch branch

1.2 Working with Patch Branches in CVS

1.2.1 Making a Patch Branch in CVS

To create a patch branch rooted from a particular version do: 

cvs rtag -b -r release-4_2 release-4_2_patch ccp4
It is possible to checkout (and thus presumably export) branches. It is also possible I think to make branches from branches, so in fact we would probably do: 
cvs rtag -b -r release-4_2 release-4_2_1 ccp4     [branch from release]
cvs rtag -b -r release-4_2_1 release-4_2_2 ccp4   [branch from branch]
and so on. So this provides a mechanism for making patch releases.

Alternatively: can we tag the branched files? e.g: 

cvs rtag -b -r release-4_2 release-4_2_patch ccp4 [make branch from release]
cvs rtag -rrelease-4_2_patch release-4_2_1 ccp4   [tag all files in branch]
cvs export -release-4_2_1 ccp4                    [export tagged files]
I'm not sure if this is possible. It mignt require something more convoulted e.g. check-out a working copy based on the patch branch, then tag the working copy. Or it might not possible at all. Does anyone know?

1.2.2 Merging/separating Patch and Developmental Changes

Bug fixes to the current release must be commited to the current patch branch - otherwise they will not be available when we make patches, new versions etc. Developmental changes can be commited in the main branch and this way are kept separate from the fixes.

To make and commit developmental changes just do things as before.

To add a change to the patch branch, we currently use the procedure: 

cvs update -r release-x_y_z_patch file
[make changes to file]
cvs commit file
cvs update -r latest revision file
cvs update -A file

Alternatively it is possible to merge changes from the patch branch into the main branch using the -j option of update, e.g. 

cvs update -j R1fix m.c
but of course you still need to have made the patch in the first place. Also there are more than likely complications to do with merging different revisions - so using this may be a non-starter. Needs more thought.

1.2.3 Making Releases and Patches (diffs) from Patch Branch

See 1) for exporting patch branches (need to check that this works). Making patch files is straightforward: 

cvs diff -c -rrelease-4_2 -release-4_2_1 > patch-4_2-4_2_1.diff
I would plan to supply patches between each minor release. This would mean that someone wanting to go from 4.2 to 4.2.2 would need to apply two patches, but it is so fast that I don't see this as a problem.

2. User Side

2.1 Applying Patches to update an installation

The patch files will be generated as above. The patch program will do the job of applying the patches recursively:

cd $CCP4
ftp ccp4a.dl.ac.uk ... i.e. fetch the patch file to this dir
patch -N -p1 -i patch-4_2-4_2_1.diff
Then reconfigure and build.

Explanation of patch options: -N means "ignore patches which have already been applied." -p1 is required to match up the directory and file names within the patch.

NB If there are substantial changes it is possible that the patching mechansim might fail.

3. Other issuse

3.1 Making Binaries for Patch Releases

The idea is that once a patch release has been created we will rebuild the binaries and put them on the ftp site. We have aleady provided binaries for IRIX, OSF1 and NT/Windows. We should also provide them for Linux and MAC-OSX?

There is a script in /ccpdisk/xtal/auto-build/bin called auto-build-binaries.csh, which should automatically create the packaged files for whichever system it is run on. There is a complication with static builds on OSF1 which is currently resolved by manually creating an appropriate config.status file and using this instead.

3.2 Reporting Problems & Fixes to Users

My original idea was to maintain a problems page with two sections:

  1. List of available patches, with dates, summaries of contents and links to download them
  2. Below this a list of problems similar to that which we have now, except that users are referred to the appropriate patch instead of having the diffs etc directly in the page.

One effect of this idea is that there will be a lag in providing fixes to users. I'm not sure how to get around this.

I suggest we keep a file for recording the fixes in each patch version. When the patch release is made then this is incorporated into the problems page and a new file is started. We might also want to advertise lists of reported bugs?

3.3 Tracking version numbers

Basically, how do we know which patches have been applied? The "ccp4_program -i" mechanism now prints out the patch level - so we must update this number in the code before making each patch release.

3.4 Frequency of Patch Releases

This is the big question! Too frequent means a lot of extra work for DL staff, too infrequent means fixes take a long time to percolate down to the user comm