Need some quick tips on Subversion best practices, covering everything from structuring your repository, to avoiding merge hell, and advice on testing? In this post, we share some rapid-fire advice for busy developers who need to get the most out of Subversion straight away.
Subversion gives users the freedom to structure their repository according to a project’s particular needs, but if you don’t implement a logical project layout, you’re running the risk of creating an administrative nightmare. Here are some general rules worth bearing in mind when creating a new Subversion repository, to ensure all that freedom doesn’t lead to complications!
- The trunk shouldn’t break – the trunk should always be stable, and should always compile. To ensure the trunk doesn’t break, all risky development should be confined to the branches, and CI and automated regression testing should also be considered, to ensure there is no regression in the trunk.
- Use tags – tags should be used to make snapshots of your project at certain points along the development process (e.g tagging a copy of ‘Release 1.0’.) It can also be useful to make snapshots of your code before implementing major new features, in case you need to roll back to before a feature was introduced.
- Working copies should always be checked out from the top level of the branch/trunk – i.e /trunk or /branches/(branch name)
- The root directory of the working copy should be named after the branch that it is checked out from (e.g “ProjectA”)
- Make structural changes to the trunk – structural changes to the repository (directory or file renaming, and directory or file deletion) should always be performed on the trunk, at a time when there are no outstanding branches waiting to be merged. This can help teams avoid serious merge conflicts.
Want more advice on setting up your repository? For more information, see our post Subversion Best Practices: Repository Structure
Branching & Merging
Branching and merging can be a pain-point for Subversion users, but when used correctly, branching and merging is one of the most powerful tools at your disposal. Here are some tips for avoiding merge hell – and that dreaded merge conflict!
- Make use of log messages – when performing merges, it is good practice to leave as much information in the log message as possible (what changes were made, why, and by whom, etc.) Remember, the more information you provide, the easier it will be months down the line, when you need to find out if a particular branch was ever incorporated into the trunk.
- One thing at a time – when performing a merge, it is important to isolate the merge (i.e only make changes that are necessary to resolve the conflict) – do not add any additional planned development before performing the commit. Likewise, do not commit unrelated code changes in the same commit (i.e two bug fixes in one commit). Both of these actions make it difficult to distinguish where changes originated from, and can cause major headaches if the team decides to roll back to a particular revision.
- Use branches – branches should be created for new features and major bugs. Bug fix branches are particularly useful, as they allow bugs to be worked on immediately, regardless of the work underway in the trunk, or in neighbouring branches.
- Use ‘svn update’ – branches should be kept up to date with changes committed to the trunk, by regularly running ‘svn update’. Even if it seems your changes have little to do with the rest of the team, by the time you’ve finished perfecting your branch, the trunk may have evolved to the point that it’s a nightmare to merge your changes.
It is good practice to also run ‘svn update’ on the working copy before you begin making any changes. This ensures that your working copy is up to date with the latest version in the repository.
- Commit often – commit small changes frequently, as oppose to committing many small changes in one large chunk. This will help reduce the chances of encountering merge conflicts, and will help reduce the complexity of conflicts that do occur.
- Delete unwanted branches – branches that are no longer required can be deleted. There are several reasons why you may decide to delete a branch, but the main ones are:
– To reduce clutter.
– A successful merge has been performed, and the branch is now redundant.
– A successful reintegration merge has been performed, and any future reintegration of that branch will confuse Subversion’s merge tracking capabilities.
Branches should not be deleted to reduce the repository size, as deleting branches does not actually remove them from the repository, it just removes them from the HEAD revision.
For even more information on branching and merging, check our out blog on Best Practices for Merging in Subversion
And lastly, test everything! Get into the habit of systematically testing every feature and bug fix implemented after merging, and consider CI and assertion testing on feature branches, which are useful for indicating code maturity and progress. As a minimum, automated regression testing should occur on the build of the feature branch.