Karl Katzke

Subversion is a software package that helps you manage versions and releases of your software, similar to the older CVS (Concurrent Versioning System).

There are several strategies for managing software releases with Subversion, mostly dealing with how you branch and merge branches back into the trunk. The proper one for your organization will depend on what kind of software you write, and how you schedule and label your releases.

What Subversion Does

For those unfamiliar with Subversion (svn for short), it’s a package that maintains different versions of your software in it’s database or filesystem, and tracks what changes were made to different lines of files between each and every commit. Subversion also helps many developers work on a project together without making changes to code that will adversely affect others code.

A commit is when a developer places code changes from his work area into the central repository. A check-out or update is when a developer downloads code into their working area. At every commit, a developer is required to make comments on the things that they changed, which can be reviewed in the log by other developers when they check out code or are looking back through the ‘history’ to find where their code was broken. At update time, a developer will also see any ‘conflicts’ or ‘overwrites’ that are happening to the code in their working area.

Subversion will also let you maintain different “branches” as well as a “trunk” and “release tags” for your software. The way that you manage these different attributes will differ depending on your needs, most specifically what kind of software you write and what kind of versioning system you need. You can keep copies of the source code in any set of folders that you want; you don’t have to follow the Branches/Tags/Trunk schema that is the default. I generally use Branches and the Trunk most, and create a Releases directory to replace the Tags directory.

To move code into branches or tags, the svn copy command works like a charm. You can use

svn copy http://path/to/repo/trunk http://path/to/repo/branches/branchname

(or file:///path/to/repo, if you’re set up that way). ’svn move’ will work the same as ’svn copy’.

The Trunk is the “current version” of your working area. This is typically the area where everyone works together on a project, and typically contains the current development version. If you’re working alone on a project and your website is always the latest version that’s been tested in subversion, you shouldn’t need to use tags and branches.

Branches can be used to contain working areas. Let’s say you need a sandbox to play with a particular feature. Copy the trunk to a new branch using ’svn copy’. Then check that branch out to your working directory, make your changes, and commit them back into the repository. Your changes will live in your branch until you merge them back down to the trunk. Note also that the trunk will continue to move along without updating your branch, you’ll need to use ’svn merge’ to move changes from the trunk to your branch, and then back down to your trunk.

Tags are typically used to contain snapshots of the code at various moments in time, such as “1.0-release”. This is useful for testing and maintaining copies of your code at particular supported versions. (I tend to create a path/to/repo/releases folder instead of path/to/repo/tags, but that’s personal preference.)

What kind of code do you write?

I’ve found Subversion to be useful to manage both desktop applications AND web applications… but in very different ways. Desktop applications are usually written in a complied language, and nightly compilations can be built using code checked into the subversion repository in different branches or the trunk. Web applications are written in scripting languages, and most times can’t be taken down for patching. Subversion can help you instantly update the source code — even while users are ‘live’ in the system — and also make any changes to the underlying database structure.

Source control enables testing

One of the best features of Subversion is the ease with which you can move information between branches, tags, and the trunk. Let’s say you have a Release Candidate version. You check in the final modification, and then you issue an ’svn copy’ command as explained above to move that ’snapshot’ of the code into a tag. Your quality assurance people (aka ‘testers’ … or if you’re Microsoft, ‘users’…) can then copy that release candidate and test against a static version.

Beware: If you keep making fixes and updates to that tagged version, your testers encounter a ‘moving target’ — things they’ve already tested may be broken by your updates. You should leave your tag as static, and work in a branch. When the testers have either hit brick walls or found all the bugs there are to find, and you’ve fixed all of them, THEN you should release another Release Candidate in Tags and start testing over again.

Using Source Control for Documentation

If you don’t have a documentation management solution in place already, Subversion can do that too. If you keep your documentation in .html files or another equally portable flat file format, you can keep the files in a directory off of root or off of your trunk, and track the changes to your documentation at various releases. The Symfony Project (mentioned below) used this tactic to manage chapters of their book. This can also help you ensure that developers make appropriate changes to the documentation as they make changes to the code or interface.

SVN as a Backup Solution

For one project, we needed to keep hourly database backups and be able to step back in time to recover from data corruption. As a result, we started dumping every table to a separate flat file every hour, and then performing an ’svn commit’ after all files were done dumping. As a result, we could simply search for the appropriately timed version of the table and reload it at need.

Regardless, keeping your repository in a separate location from your production environment will ensure that you have a most recent copy of your code if something unfortunate should happen to your production environment.

Tips and Tricks

• Use –file-type=fsfs to keep files in a Filesystem as opposed to Berkeley DB database. The filesystem database is the default as of the most recent version of Subversion, and gets around

• On Linux when using the file:/// access method, set user’s umasks to 002 (user and group read/write/execute, all read/execute) and add all developers to the same user group. Otherwise, make sure the webserver has read/write access to the entire svn repository directory tree.

Known Issues

• File permissions and BDB (Berkeley DB) errors can cause the repository to ‘hang’ for a time. Use the fsfs repository type to get around the latter, and make sure you set user permissions properly when using file:// access to get around the former… or just use the HTTP access method with apache and mod_dav_svn.
• Subversion only works with Apache 2 on the subversion server. Subversion’s server architecture will -not- work on a cpanel-managed server.
• I still haven’t found a good solution to deploying database changes simultaneously along with code changes. Some code could be written to get around this, and I’ll try to get that put together and online sometime in the near future.
• If you change binary content frequently (images, compiled programs), the amount of disk space your repository will consume may balloon rapidly. You should try to keep data that changes rapidly (log files, frequently changing images, compiled binaries, variable files, temporary files…) out of the repository.

Add-Ons

Trac is an open-source ticket management package that integrates closely with a subversion repository. There are instructions elsewhere in my blog on how to set up Subversion and Trac to work together. Trac is in active development and the version number is quite early, but it’s completely stable and exceptionally useful. Along with Trac Hacks (a resource for plugins) and future planned features, Trac makes a great project management and spec/documentation management tool.

Examples

• The Symfony Project uses Trac and Subversion extensively, including a /docs directory off of the repository root to track changes to their book.

Further Reading

The SVN Book is published in it’s most recent version online — and the documentation is, of course, managed with subversion.

If you don’t want to host your own Subversion server, CVS Dude will host a Subversion server for you for free (with tiny projects) or small projects.