SVN: How to structure your repository
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.
Summary
So, to make a long story short. Here’s how a general subversion repository may be structured:
Please let me know if I missed anything.
Good article. The only part I disagree with is the pre/post tags thing. There is really no need to do this when using Subversion and I think the clutter it creates in your tags folder outweighs the minor benefit it might bring.
If you were going to use a concept like that, you should at least name them in a way that they would sort together, such as 3391-PRE and 3391-POST.
I’d also recommend creating more top level folders. For example, maybe add a “releases” folder for the release tags. Personally, I’d just skip the bug fix tags and stick with the three main folders.
Mark
Thanks for all your SVN related articles. They have been helpful.
@Mark: You have a point. Using a lot of tags for bugfixing will make your repository a mess. This way of fixing bugs should only be used if you really can’t fix it in one commit. Most bugs can be fixed that way.
If you have a larger project, it might indeed be a sound idea to create seperate top level directory for releases and maybe even one from bugfix tags if you like.
I like things simple. Tags belong in a tags directory, period. I can use my unix commands to find what I need:
$ ls -l | grep 3391
But that’s really an opinion. There’s no right or wrong here.
@david: Thank you. If you have any other question about Subversion, please let me know. I might dedicated an article to it.
I used to package my projects this way but found it overkill for most projects that I work on nowadays.
I know this is a great structure for big projects (Adium, Eclipse, etc.) that have many “releases in the wild”, but I think just keeping the trunk in the root folder is sufficient.
Most of my applications are websites that only ever have one version – the one that is public. Ever since I replaced J2EE with Rails, I find the turn around time is so short there is no need to branch.
@Dave: I’m a pragmatic programmer. You never know what you’ll add to your project later on, so I like to be prepared. I’ve had to restructure some repositories in the past and that is a very time-consuming business. From now on I keep things organised from the start.
If you just keep your web site in SVN, you don’t have to use tags and branches if you don’t like that. But using experimental branches can be useful if you want to try a new style or add new functionality without publishing it to the web.
[...] This is a great post on how to organize your subversion repository and bring order to your release/development cycle. Probably the same principles are valid for CVS and others as well. [...]
[...] Excellent article on branching in Subversion. One thing missing is the branch timeline chart. Something like this: [...]
[...] ??????? ?????? ? Subversion ? ??? ?????????? ? ???. [...]
[...] Ariejan.net
Ariejan, thanx for all the great articles about subversion, keep them coming!
Would like your experience: how do you set up subversion to control development of your website with more than one developer? I have some questions in this area:
- Do the development team have a website configured in their own local machines, or they all have a unique remote machine to test their code? And if they use the second approach, how to set up subversion to work that way?
Maybe you could write an article about that :-)
Good Article!
I’m using SC (Subversion Automation from Peter Jones pmade.com). The mandatory “link”:http://www.pmade.com/open-source-software/sc/
It automates the rbanches, releases and bugfix tags and let you concentrate on coding and bugfixing, not repository housekeeping ;-)
SVN – Best Practices…
Denne side indeholder generelle anbefalinger vedr
Very helpful articles for someone (like me) just getting into Subversion.
However, one question I have been unable to find any answers to is how to deal with common framework code.
Like, I presume, many Object Oriented programmers, I have two types of classes that are common to most of my projects.
1. Classes that are used by the project.
2. a. Classes that are inherited from in the project.
b. Interfaces that are implemented in the project.
These frameworks may be enhanced from time to time as needed.
Should these be in separate repositories and how would you recommend linking them (with the appropriate version) to my actual projects?
Thanks,
Clive
@Clive: If you have a framework (or shared objects) you should put them in a separate repository. By using Subversion externals you can then link that repository into the repository of your current project. Changes in the framework are then available in the project as well.
I highly recommend you use a release branch as an external so you don’t introduce new (or broken) code into your project.
I’ll write an article about this later on. Thanks for asking.
[...] SVN: How to structure your repository “This article will discuss how to structure your repository in order for you to take full advantage of Subversionâ
[...] Ariejan.net – Blog Archive ยป SVN: How to structure your repository [...]
Using SVN (General)…
Introduction to SVN Subversion (SVN official site…
Thanks Ariejan for an informative article. It seems however that your example of the subversion tree at the end of the article is missing. I’m using FF2 on WinXP.
Thanks for your good work bringing subversion to the people.
[...] 2008 Java This post is a pointer to a useful post about Structuring the SVN repository in Ariejan.net. This site is very useful to find out more information about the SVN usage. Click here to see the [...]
Good article…
I have a shared hosting account in which I’ve been trying to install SVN with no success, they told me I had to get a dedicated hosting account. At SVN is already installed, so I can do svn+ssh:// but I’m looking for svn://
Does anyone know a cheap way to get it setup?
Thanks
I don’t think you should even want svn on a shared hosting account. My advice would be to find a good VPS hosting service and run you svn there. You can configure it any way you want it on VPS ;-)
[...] out the tips on structuring your new subversion repository. There are also some worthwhile tidbits on structuring the repository directories on the video, [...]
Hello Ariejan,
Its really great and helpful article. Thank a lot.
I am eager to read you article on your reply comment on May 20th, 2007
I am working on a common project which have two child projects.
So if you have already posted an article to manage bigger projects and there child projects then please show me link.
Thanks beforehand !!!
thanks for the advice :)
BTW, the image gives 404…
Hello Ariejan,
You are great man doing great thing, thank you for sharing the best understanding of version control system.
This is a great site. Are the above methods still applicable for the latest version of SVN 1.6.x. Any mentionable differences.