Subversion Best Practices

Note: This is not a tutorial. This information assumes that you already know Subversion.

Repository layout

1) You use your repository for just one software project. On the root of your repository, you should have:

branches/
tags/
trunk/

2) You use your repository for several software projects which are heavily interconnected. On the root of your repository, you should have:

branches/
   project1ExampleBranch/
   project3ExampleBranch/
tags/
   project1ExampleTag/
   project2ExampleTag/
trunk/
   project1/
   project2/
   project3/

3) You use your repository for several software projects which are not interconnected. On the root of your repository, you should have:

project1/
   branches/
   tags/
   trunk/
project2/
   branches/
   tags/
   trunk/
project3/
   branches/
   tags/
   trunk/

The Branch-When-Needed system

(This is the system used by the Subversion project.)

1. Users commit their day-to-day work on /trunk. /trunk must compile and pass regression tests at all times. Committers who violate this rule are publically humiliated.
2. A single commit (changeset) must not be so large so as to discourage peer-review.
3. If rules #1 and #2 come into conflict (i.e. it's impossible to make a series of small commits without disrupting the trunk), then the user should create a branch and commit a series of smaller changesets there. This allows peer-review without disrupting the stability of /trunk.

Pros: /trunk is guaranteed to be stable at all times. The hassle of branching/merging is somewhat rare.

Cons: Adds a bit of burden to users' daily work: they must compile and test before every commit.

General recommendations

• Always write a descriptive log message when you commit something, even if it is a little minor change (you can actually specify this in the log message itself).
• Always check merges. Be careful of automatic merging.
• Use repository hooks to ensure internal software policies. (no passwords in code, case insensitivity, etc.)
• Use reserved checkouts (locking) for binary files and other file types that can not be merged.
  • The Lock-Modify-Unlock Solution
  • Subversion Locking
  • Command line use:
    • svn lock test.py: Lock the file test.py, provided that it hasn't got a lock.
    • svn unlock test.py: Unlock the file test.py, provided that we locked the file before under my user.
    • svn lock --force test.py: Lock the file test.py. In case the file was locked by someone else, we will steal his lock.
    • svn unlock --force test.py: Lock the file test.py. Useful to unlock forgotten locks from other people.

Branch and tags recommendations

• Each release is on a branch and switch working copies to it when working (svn switch command).
  • If so, trunk must be stable always. It must pass the test bench.
• Release points are tagged.
• Never commit to tags, that is what branches are for.
• If you are no longer going to commit to a branch, delete it!
• If you, for any reason, want a read only branch, you are mistaken, what you really want is a tag.
• Branch merges are always done back to the trunk.

Bug tracking usage recommendations

• Make your bug tracking software automatically update tickets when commiting. Ex: Trac

Bibliography

• Personal experience. You can't buy it.
• Version control with Subversion book
• http://svn.collab.net/repos/svn/trunk/doc/user/svn-best-practices.html
• http://www.slideshare.net/mza/subversion-best-practices
• http://www.slideshare.net/drock/svn-best-practices-presentation
• http://bradchoate.com/weblog/2006/07/27/oscon-subversion-best-practices
• http://help.cvsdude.com/help/wiki/SVN_Command_Line_Tutorial

Suggestions: If you have suggestions, please send me an email to david.horat@cernNOSPAMPLEASE.ch

-- DavidHorat