Subversion

Introduction

Subversion (also: svn) is a version control software that allows multiple authors to simultaneously work on developing software. It is very similar to CVS, with comparable syntax and (improved) features.

The major advantage of using version control software is that different developers can work on their individual working copies. In this way, they will not modify the same piece of software at the same time, and any change will properly documented for other developers. With subversion, it is also easy to revert to earlier versions.

Within the VALD project, the following parts are under subversion control :

• Extraction tools (select, preselect, etc)
• EMS (email service) scripts
• WWW interface

This document contains examples on how to use Subversion within the VALD project. Please consult the documentation links below for more comprehensive information on Subversion.

Using Subversion

Subversion needs to be installed on your system. Most standard Linux distrubutions now include subversion in the default package selection. You check check if subversion is installed by trying the command 'svn'. If you need to install subversion, first try the software manager of your Linux distribution. Otherwise, download subversion from http://subversion.tigris.org/

Subversion documentation

The authoritative source of documentation for Subversion is the free e-book available through http://svnbook.red-bean.com/ This is a very good resource that includes background information, as well as instructions and examples. You can also get good online documentation using the built-in help function of subversion. Type 'svn help', and you'll see.

The syntax of subversion is simple :

svn <command> [filename(s)]

The command is mandatory, the filename(s) are optional. Without the filename, the command will be applied to all files in the directory as well as to files in subdirectories.

Subversion server setup and login credentials

The subversion repository that contains the VALD software is currently located on the machine that hosts the Uppsala server (vald.astro.uu.se). The server is configured such that connecting to this machine with the svn:// protocol will spawn a 'svnserve' process through xinetd. Only authorized users/mirrors can connect to the repository. Authorization and data transfer is encrypted using the SASL2 module. See the Subversion manual at http://svnbook.red-bean.com/ for more details on this setup.

A list of users and passwords can be found on the SubversionClientCredentials page. If you do not have any assigned username/password, please ask the VALD manager to create one for you (with "saslpasswd2 -c -f /etc/my_sasldb -u VALD3 username").

Basic usage of subversion (specific for VALD3)

1) Checkout a working copy

The Subversion repositories for VALD are only available through the subversion+ssh protocol. You can checkout your own working copy with one of the following commands :

svn checkout svn://vald.astro.uu.se/VALD3

(The Inside VALD document is now no longer in subversion, but included in this Wiki).

You obviously will need to know your username and password to do this (see above), but you only need to do this once - your login credentials will be saved to your local disk. Once the download is finished, you will have a subdirectory structure containing all the files of your tree.

You only need to check out a working copy once. From then on, you will be able to make modifications and check updates, like the examples below.

2) Check your existing working copy against the repository

Before you start to make any modifications, you should check that you really have the latest version on your system. The following commands will show you the status of your files :

svn status
svn status -v
svn status -u

The first command only lists files that are not identical to (or not included in) the files in the repository. The second command gives a more verbose listing, including non-modified files. The third command forces svn to contact the repository, so it will also report modifications after your last call to 'svn update' Use 'svn help status' for an explanation on the different tags used.

3) Bring your working copy up to date

If there are differences between your files and the repository, you can bring your own copy up to date with

svn update

If there already are changes in your own copy, these will be merged with the version in the repository. Subversion will also indicate if there are conflicts between your version and the repository. You will have to resolve such conflicts manually.

4) Make changes to your working copy

Now, you can start to make changes to the files. Remember to include explicit comments in the source code. Test the new product. Do not make too many changes at once - resolving one problem at a time is normally more than enough.

Because subversion keeps track of all changes, you need not comment out old code for future reference.

5) Inspect your changes

Once you are happy with your changes, you should review your changes against the files in the repository with

svn diff

This produced a 'normal' diff of your working copy and the repository.

6) Commit your changes

Once you are fully satisfied with the changes, you must commit your changes to repository, with

svn commit

This will send your changes to the repository, and open an editor to let you enter a description of which changes you made. Be explicit here and sign your work with your name! This information is what other developers will use to track your changes. Also, the software development will be easier to follow if you make small incremental changes, and commit these on the way.

7) More ways of interacting with the repository

The examples above is idealized, with the assumption that there are no changes made by other developers on the way. There are several subvversion commands available to help you merge code, resolve conflicts, add and remove files etc. For example, if you create a new file, and want to add this to the repository, you need to do this with 'svn add'.

For a more detailed description, please consult the svn manual, and in particular the 'common working cycle' ;

• http://svnbook.red-bean.com/

• http://svnbook.red-bean.com/en/1.4/svn.tour.cycle.html

FINALLY

Once you commited changes to the repository, the software on the server will not be updated immediately. Currently, each server runs a cronjob that checks and updates the server's software once a day.

REMEMBER

• To clearly document all changes
• To sign your work with your name
• To only include the source code in the repository (no compiled executables, no linelists, no model atmospheres)
• To not directly edit the software on the server. Use your own checked-out working copy instead!
• That changes can be easily be undone