PSI3 SVN Policies: Which Branch Should I Use?

The PSI3 repository is comprised of a main trunk and several release branches. The branch you should use depends on the sort of work you plan for the codes:

1. For any piece of code already in the most recent release, bug fixes (defined as anything that doesn't add functionality -- including documentation updates) should be made only on the most recent stable release branch.
2. The main trunk is reserved for development of new functionality. This allows us to keep new, possibly unstable code away from public access until the code is ready.
3. Code that you do not want to put into next major release of PSI3 should be put onto a separate branch off the main trunk. You will be solely responsible for maintenance of the new branch, so you should read the SVN manual before attempting this.

Fig. 1 provides a schematic of the SVN revision-control structure and branch labeling. Two release branches are shown, the current stable branch, named psi-3-3, and a planned future release, to be named psi-3-4. The tags on the branches indicate release points, where bugs have been fixed and the code has been or will be exported for public distribution. As soon as a release branch is created, we generate a tag so that we may make updates to that version of the code without affecting other branches or the main trunk. The dotted lines in the figure indicate merge points: before each public release, changes made to the code on the stable release branch will be merged into the main trunk.

Figure 1: PSI3 SVN branch structure with examples of branch- and release-tag labelling.

A frequently encountered problem is what to do about bug fixes that are necessary for uninterrupted code development of the code on the main trunk. As Rule 1 of the above policy states, all bug fixes of the code already in the recent stable release must go on the corresponding branch, not on the main trunk. The next step depends on the severity of the bug:

1. If the bug fix is critical and potentially affects every developer of the code on the main trunk, then PSI3 administrators should be notified of the fix. If deemed necessary, appropriate steps to create a new patch release will be made. Once the next patch release is created then the bug fixes will be merged onto the main trunk. If the bug fix doesn't warrant an immediate new patch release, then you can incorporate the bug fix into your local copy of the main trunk code manually or using SVN merge features. This will allow you to continue development until next patch release is created and the bug fix is incorporated into the main trunk code in the repository. However you should never merge such changes into the main trunk yourself.
2. If the bug fix is not critical (e.g. a documentation update/fix), then you should wait until next patch release when it will be merged into the main trunk automatically.

The following are some of the most commonly used SVN commands for checking out and updating working copies of the PSI3 source code.

$\bullet$ To checkout a working copy of the head of the main trunk:

svn co https://sirius.chem.vt.edu/svn/psi3/trunk/ psi3

$\bullet$ To check out a working copy of the head of a specific release branch, e.g., the branch labelled psi-3-3:

svn co https://sirius.chem.vt.edu/svn/psi3/branches/psi-3-3 psi3

Note that subsequent svn update commands in this working copy will provide updates only on the chosen branch. Note also that after you have checked out a fresh working copy of the code you must run the autoconf command to generate a configure script for building the code. (See the installation manual for configuration, compilation, and testing instructions.)

For each of the above commands, the working copy of your code will be placed in the directory psi3, regardless of your choice of branch. In this manual, we will refer to this directory from now on as $PSI3. Subsequent SVN commands are usually run within this top-level directory.

$\bullet$ To update your current working copy to include the latest revisions:

svn update

Notes: (a) This will update only the revisions on your current branch; (b) The old -d and -P flags required by CVS are not necessary with SVN.

$\bullet$ To convert your working copy to the head of a specific branch:

svn switch https://sirius.chem.vt.edu/svn/psi3/branches/psi-3-3

$\bullet$ To convert your working copy to the head of the main trunk:

svn switch https://sirius.chem.vt.edu/svn/psi3/trunk/

$\bullet$ To find out what branch your working copy is on, run this in your top-level PSI3 source directory:

svn info | grep URL

This will return the SVN directory from which your working copy was taken, e.g.,

URL: https://sirius.chem.vt.edu/svn/psi3/branches/psi-3-3

Some words of advice:

1. Most SVN commands are reasonably safe,

2. Unlike CVS, you shouldn't use svn update to see the status of your working copy. With SVN you should use svn status to see if you've modified any files or directories. If you want a direct comparison with the repository, you should use svn status -u.
3. Read the SVN manual. Seriously.
   http://svnbook.red-bean.com/en/1.2/svn-book.html
4. If you're about to start some significant development or bug-fixes, first update your working copy to the latest version on your branch. In addition, if you do development over a long period of time (say weeks to months) on a specific module or modules, be sure to run a svn status -u occasionally. In can be very frustrating to try to check in lots of changes, only to find out that the PSI3 has changed dramatically since your last update.