Using Subversion (SVN) and Trac

My current repository for SVN and Trac is at sd-2116.dedibox.fr.

Using Trac

If you do not need to modify the code for a software project or a paper directly, you can just browse the list of Trac projects. Some projects are password-protected, so you will need to get a username and password from me. Note that the SVN and Trac usernames and passwords are the same.

When you first log in to a new Trac project (one you haven't visited before), make sure to click on Preferences at the top right of the screen, and enter an e-mail address in your profile. You will then be notified of changes to tickets you raised or are responsible for.

The principal actions you can take in a Trac project are:

Browse the source code, whether for computer code or a paper.
Read and edit the Wiki for the project.
Create tickets, which can be bug reports or new feature suggestions. For papers and grant proposals, tickets can include reporting typos, errors, improvements, new sections, discussions on a particular topic, future work, etc.

Tickets are the most important part of Trac: they allow a global view of what needs to be done for a project. When you create a new ticket, you assign it to yourself or another collaborator, who will then decide to accept it or re-assign it to somebody else. You can also add extra users who will be CC'd whenever a ticket changes. After posting responses and fixing what has to be fixed, a ticket is closed by marking it as resolved. If other users disagree, a ticket can always be re-opened!

The two most powerful aspects of Trac are (i) Almost everything can use Wiki formatting, so that bullet lists, font attributes, etc. can easily be created (even latex!). (ii) Trac Links can be used to cross-link throughout a project. For instance, write "ticket:3" anywhere (even in SVN log messages) and a link to ticket number 3 is automatically generated. Write [23] to link to changeset 23, or source:trunk/paper.tex to link to the latest version of a paper.

For more information see the Trac Guide.

Some tips:

Accept ownership of a ticket when you start to fix it. Not only is this useful for sorting later, but Trac then also notifies you of ticket changes by e-mail (as long as you provided your e-mail address as above).
Let the ticket reporter close the ticket, unless you are certain it's a trivial fix (or the reporter is lazy). In any case, the reporter is free to re-open the ticket if he/she is unhappy!
Add comments to your Subversion commit log such as "Closes ticket:3." or "(See ticket:4)". Trac will automatically hyperlink this to the ticket. In fact you can use Wiki formatting in your Subversion log messages.
Similarly, when you close a ticket as "fixed" add a comment to the ticket such as "Fixed in [67]", where 67 refers to a Subversion changeset. Again, the [67] will get hyperlinked. This way it's easy to see the diffs that were made for a given version, and how the ticket was resolved.

Using Subversion

First, get a subversion client (command line: svn) if you don't already have one, which is available for all the popular platforms such as Linux, Windows, Mac, etc. On Linux distributions it can usually be installed via the package manager.

To "check out" (i.e., to get your own local working copy) of a project, just type

    svn co svn://sd-2116.dedibox.fr/rodent/trunk rodent

at the command prompt. Depending on access restrictions for a project, you might be asked for a username and password. (Note that the SVN and Trac usernames and passwords are the same.) Here the project name is rodent, and you are checking out ("co") the trunk of the project, that is, the main development tree. The last instance of rodent on the command line is the local name given to the directory, which you can call anything (for example if you want to check out multiple versions of the same code).

Now you can edit the files and make changes as usual. If you want to add a new file or directory, just create it as usual, and then

    svn add new_file_or_dir

Note that new additions don't get uploaded to the repository until you commit them, as described below.

To "commit" local changes once you're satisfied with them, use

    svn ci

If you haven't before this point, you will be asked for a username and a password, and an editor will pop up for you to enter a log comment. Write something descriptive, and a new revision is created (also called a changeset). Revisions are numbered consecutively and refer to the development tree as a whole, so referring to "revision 49" uniquely determines the state of the entire project repository.

To make sure you have the latest version when you return to a project that you previously checked out, execute the "update" command

    svn up

from within the local directory of your working copy.

Other useful SVN commands include

    svn stat

which gives "status report" of the current state of your local files (M = Modified, ? = not under version control), and

    svn diff

    svn diff paper.tex

which lists the differences between local file and the original file. It is also useful to view the change history (or log) for a file or directory:

    svn log paper.tex

Some tips:

Do not be afraid to commit changes! Subversion remembers everything before your commit, so it is impossible to break anything.
Commit changes often! It is better to have a detailed log of small changes than a huge number of simultaneous changes. In particular, if you don't commit changes often you will forget what you changed (though liberal use of "svn diff" helps to figure that out).
Write helpful log messages! It takes a few seconds more but it's worth it. If your changes correspond to a Trac ticket number, refer to it in the SVN log as "ticket:3". It will be automatically linked within Trac.

Advanced Features

Branches: If you want to play around with your own version of the tree for a while, simply create a branch with
```
    svn cp svn://sd-2116.dedibox.fr/rodent/trunk svn://sd-2116.dedibox.fr/rodent/branches/mybranch
```
called here mybranch, and then check out a copy of it
```
    svn co svn://sd-2116.dedibox.fr/rodent/branches/mybranch myrodentbranch
```
The difference between creating your own branch vs getting a working copy of the trunk is that now you can commit changes to your branch, and they will not be reflected in the main trunk. This is useful for trying new things that require nontrivial development. Eventually you might want to merge your branch with the trunk, or simply abandon it.

In Subversion branches are simply copies of the tree, but copying is free since the program doesn't not actually duplicate the files. It only remembers internally that the two copies refer to a common file (unless you start changing one of the copies, in which case changes are tracked separately).
Tags are a good way of marking important versions of a code or paper. For instance, if you are submitting a paper in the repository called mypaper to a journal, you can tag the current version as the submitted version by issuing
```
    svn cp svn://sd-2116.dedibox.fr/mypaper/trunk svn://sd-2116.dedibox.fr/mypaper/tags/submitted
```
Just like branches, tags are simply copies of the main trunk (though again the files aren't actually copies — they just appear to be). The main difference is that tags are only expected to be checked out, not modified. You can view all the tags in a project with
```
    svn ls svn://sd-2116.dedibox.fr/mypaper/tags
```
or check out a tagged version with
```
    svn co svn://sd-2116.dedibox.fr/mypaper/tags/submitted
```
Again, the goal is to organise the structure of the repository to remember exactly where things were. If six months later Referee B says "On page 6 line 8", but we've since added 300 lines to the paper, we can check out the tagged version to see what he or she is talking about.

For more information see the Subversion Book.