SVN: How to structure your repository

Friday 24 November 2006

You are reading an article about Subversion. That's great, because it means you're thinking about the benefits of version control for your project. However, I have long since moved from Subversion to Git. I strongly recommend you read up on my Best Practice - The Git Developmenet Cycle. Git is much faster an flexible than Subversion, go check it out now!

Most people know what Subversion is and that there's something called "The Trunk" with code in it. Well, there's more to your SubVersion repository than you think! This article will discuss how to structure your repository in order for you to take full advantage of Subversion's possibilities.

As you may have read in my previous Subversion articles the base of your Subversion repository are three directories: branches, tags and trunk.

Each directory in subversion can be checked out seperately. See the examples for more information. ~

Trunk

The trunk contains the most current development code at all times. This is where you work up to your next major release of code.

I see, almost too often, that people only use the trunk to store their code. Releases are pulled from a certain revision and then development continues. This is no good. Not for you, not for your product.

The trunk should only be used to develop code that will be your next major release. Don't brand the trunk with version numbers or release names. Just keep the trunk in "development mode" at all times.

Example:

https://svn.example.com/svnroot/project/trunk

Branches

There are different types of branches. I'll tell you about the most common ones here.

With the branches directory you can create paths for you code to travel to more specific goals like an upcoming release. As I discussed in my article on releasing software from Subversion the branches directory contains copies of your trunk at various stages of development.

Release Branches

We have already seen the RB-x.x release branches. When the trunk reaches the stage that it's ready to be released (or when you want to freeze the addition of new features) you create a release branch. This release branch is just a copy of your current trunk code.

The branch can be checked out seperately and you can start branding and versioning the project. You can also use the release branch to fix bugs that pop up during (beta) testing (See my article on that too). The idea of this is to keep development in the trunk going without being bothered by release specific stuff. So it's perfectly fine to add new features to your trunk while you (or others) prepare the release.

Of course, you can address a release branch directly to check it out:

https://svn.example.com/svnroot/project/branches/RB-1.0

Bug fix branches

Branches may also be used to address the more serious bugs found in the trunk or a release branch. The bugs are of such a magnitute that you can't fix them by yourself in a single commit. So, in order to focus on the problem of fixing this bug you should create a new branch for this purpose. This allows development in the trunk or your release branch to continue, and you won't disturb them with new bugs or tests that break the current code.

Bug fix branches are named after the ID they are assigned in your bugtracking tool. Mostly this is a number: BUG-3391

Of course, you can access your bugfix branch like any other.

https://svn.example.com/svnroot/project/branches/BUG-3391

Read my how to fix bugs properly article for more specific bug fixing information. Also read on in this article to the tags section.

Experimental branches

Something that also happens a lot is the introduction of new technologies. This is fine, of course, but you don't want to bet your entire project on it.

Imagine that you want to change from PHP 4 to PHP 5 for your web application. How long would it take you to convert your entire project? Do you want your entire code base (trunk) to be useless until you have converted all of your code? Probably not!

These experiments, maybe PHP 5 is a bridge too far for your app, should be given their own branch. You can hack your way to PHP 5-ism there and if you fail, you still have your current PHP 4 code in the branch.

Experimental branches may be abandonned when the experiment fails. If they succeed you can easily merge that branch with the trunk and deliver your big new technology. These branches are named after what you're experimenting with. I always prefix them with 'TRY-':

https://svn.example.com/svnroot/project/branches/TRY-new-technology

Tags

Tags are, like branches, copies of your code. Tags, however, are not to be used for active development. They mark (tag) a certain state your code is in.

Release tags

Release tags mark the release (and state) of your code at that release point. Release tags are always copies of the corresponding release branch. Release tags are prefixed with 'REL-' followed by a version number.

You can access these tags easily:

https://svn.example.com/svnroot/project/tags/REL-1.0.0

See my article on releasing software for more information.

Bug fix PRE and POST tags

When you have created a bug fix branch, you want to mark (tag) the situation of your code before and after the bugfix. This allows you to easily refer to the changes you made when you want to merge them back to your trunk or release branch.

The start-tag is called 'PRE' and the end-tag called 'POST'. Of course, you should add the bug ID number here too to show what bug you are tagging here.

You probably don't check out bug fix tags, but you want to reference them when merging bug fixes with your other code:

https://svn.example.com/svnroot/project/tags/PRE-3391
https://svn.example.com/svnroot/project/tags/POST-3391

Read more on fixing bugs wiht subversion in my other article.

Did you enjoy this post? Your generosity is much appreciated.