As I mentioned before, Subversion is critical to daily development at Urbansquall. Subversion has a lot of really fancy features that can help make development a lot less stressful even for a lone developer. Today I’m going to go over one of the features that we’ve found particularly useful working in a team, and that is the concept of Trunks, Tags and Branches in a repository.

The simplest way to use Subversion is simply to dump everything into some sort of structure in your repository and then to go about your business. The reality is that this is more than sufficient for a lot of projects. But, particularly for projects that will be evolving as they are reused over several years, like a networking library for example, or a larger game that is being worked on by 4 people at any given time, the concept of Trunks, Tags and Branches can make it a little easier to keep people from stepping on each other’s toes as they are going about their business.

Trunks

Trunks is the easiest part of the TTB paradigm to understand. The Trunk is basically equivalent to what your repository would have been without using TTB. Trunk represents the active state of development shared by the majority of the team, and is assumed to be a non-official release that is in a buildable state.

Tags

Tags are most useful when you want to flag a specific state of the Trunk. Let’s say you’ve officially hit 1.0 and you are ready to do a public release. You might Tag trunk at 1.0 as you do the release, and then start development on some 1.5 features that you want to include. In this case, a user might find a bug in 1.0. You can’t patch your pre-1.5 version trunk because your 1.5 features are incomplete and shouldn’t be released. Because you tagged 1.0, you can check out that specific tag, make your bug fix, and then cut a 1.0.1 build that fixes that bug but doesn’t introduce any of the messiness of your partially implemented 1.5 features.

Tags are essentially a stamp for a noteworthy state of the Trunk that might be useful to return to in the future.

Branches

Branches are the trickiest part of the TTB paradigm, but they are probably the most useful. Branches come into play when we are considering actions that would disturb the Trunk or make the Trunk otherwise unbuildable. A good example we had recently on a project was that we had to recode the vast majority of the networking layer that a game was using. The game was working fine with the current networking layer, but the new networking layer would deal with a lot of the lag issues we were experiencing. The problem was that this networking layer rewrite was going to take weeks and would affect at least as much as 40 source files in the game engine itself. We used branching here for the following reasons:

1. The rewrite was complicated and would require many iterations, and we wanted the benefit provided by SVN in terms of being able to revert or inspect the revision history.
2. The game was undergoing active development from other developers at the same time the engine rewrite was occurring. We needed to make sure that all these updates would be merged into our rewrite so that no work was lost and also that we didn’t prevent these other developers from working while the networking engine was in a half-working state.
3. We weren’t sure that the rewrite would even work, so we wanted to be able to throw it away if failed.

So, we branched the code, rewrote the networking engine, and made sure we updated against Trunk frequently to keep up with everyone else’s commits. When the new networking engine was stable enough to replace the old networking engine, we could simply merge the Branch back into the Trunk without affecting the other developers who had been working on the project.

Structure

It’s easiest to put TTB into your project at the start. SVN actually makes this almost stupidly easy. At the root of your repository, just create three directories: trunk, branches, tags. Leave branches and tags empty and then put everything (source code, docs, art, etc.) into trunk like you would have done before. When you do your checkout, instead of doing “url.com/my_repository” you would now just checkout “url.com/my_repository/trunk” and you can forget about it until you find you need it one day. That’s pretty much it, if you find you need to do a Tag or a Branch in the future, you simply right-click on your Trunk folder (assuming you are using TortoiseSVN), and choose Tag or Branch as appropriate.

The specifics of Branching can get a little more complicated, so I suggest you do a little more in depth reading into the topic when you think you might need it just so you can make sure you do it correctly. It’s not complicated but there are some gotchas that you will want to understand first.

Conclusion

The TTB paradigm is not a complicated one. It stays out of your way until you need it, and it only requires a moment of effort to set up when you are first getting a project going. If you think you may have some use for it, it might be worth doing a little more reading on the subject, as SVN supports TTB quite well. It is very efficient at storing Tags and Branches, and you can typically do both while adding only a fractional increase to the size of the stored repository because SVN is smart about storing only the changes between the Trunk and the Tags or Branches (rather than an actual deep copy).