SVN trunk, branches and tags

In this post, I provide details about how I personnaly handle SVN trunk, branches and tags. This approach is also known as “branch always”, with minor differences. This might not be the best approach, but it will give beginners some explanations on what trunk, branches and tags are, and how to handle them.

Of course, feel free to leave comments on this post if some clarifications are needed, if some mistakes were made, or if you disagree with my statements.

An easy comparison

Working with SVN is somewhat like growing a tree:

• a tree has a trunk and some branches
• branches grow from the trunk, and thinner branches grow from thicker branches
• a tree can grow with a trunk and no branch (but not for long)
• a tree with branches but no trunk looks more like a bundle of twigs fallen on the floor
• if the trunk is sick, so are the branches and eventually, the whole tree can die
• if a branch is sick, you can cut it, and another one may grow
• if a branch grows too much, it may become too heavy for the trunk, and the tree will fall down
• when you feel your tree, your trunk, or a branch is nice looking, you can take a picture of it to remember how nice it was that day

Trunk

With the “branch always” approach, the trunk is the main place were stable code can be found. This is like the assembly line of a car factory, putting finished car parts together.

Here is how you should deal with a SVN trunk:

• do NEVER work directly on the trunk, unless you have to deal with a bug which is quick and easy to fix (a few characters), or if you have to ADD a few files which hold no logic (like media files: images, videos, css, etc)
• do not make too many exceptions to the previous statement, those are really special cases, every other situation must imply the creation of a branch (see below)
• do not commit changes (from a branch merge) to the trunk which may break it
• if at some point you happen to break the trunk, bring some cake the next day (“with great power comes… huge cake”)

Branches

A branch is a “cheap copy” of a subtree (ie, the trunk or a branch) of a SVN repository. It works a little bit like symbolic links on UNIX systems, except that once you make modifications to files within a SVN branch, these files evolve independently from the original files which were “copied”. When a branch is completed and considered stable, it must be merged back to its original copy, that is: back to the trunk if it was copied from the trunk, or back to its parent branch if it was copied from a branch.

Here is how you should deal with SVN branches:

• if you need to alter your application or develop a new feature for it, create a new branch from the trunk, and make your development on that branch
• new branches must be created from the trunk, except for new sub-branches (if needed) which must be created from a branch
• when you create a new branch, you should switch to it immediately; if you don’t, why did you create the branch in the first place?

Tags

Internally, SVN branches and SVN tags are the same thing, but conceptually, they differ a lot.
Remember the “take a picture of the tree” thing written earlier? Well, this is exactly what a SVN tag is: a snapshot with a name of a specific revision of the trunk, or of a branch.

Here is how you should deal with SVN tags:

• as a developer, do never switch to/checkout from/commit to a SVN tag: a tag is some sort of “picture”, not the real thing; tags are to be read, never written
• on specific/critical environments (production, staging, testing, etc), checkout and update from a fixed tag, but do never commit to a tag
• for the aforementioned environments, create tags with names like “production”, “staging”, “testing”, etc. You can also tag by sofware version and/or by project maturity: “1.0.3″, “stable”, “latest”, etc.
• when the trunk is stable and ready to be released publicly, re-create tags accordingly, then update the concerned environments (production, staging, etc)
• do not tag a tag

Example workflow

Say you have to add a feature to a project under version control. Here are the steps you should achieve to do so:

• get a new working copy of the project (through a SVN checkout or a SVN switch) from the trunk
• create a new SVN branch and give it a name which allows to understand what it is all about (say, “feature-faq-development”)
• SVN switch to the new branch (“/branches/feature-faq-development”)
• make the needed development to complete the new feature (and of course, make a lot of tests, even before you start coding), commit sub-parts of your development when needed
• once the feature is complete and stable (and committed), merge the trunk into the branch and resolve conflicts if there are some, then commit your changes
• with the approval of your peers, switch to the trunk
• merge your branch within your working copy (trunk), and resolve conflicts if there are some
• re-check your development with the merged code
• if possible, ask one of your peer to do a code review of your changes with you
• commit your merged working copy to the trunk
• if some deployment must be achieved on specific environments (production, etc), update the related tag to the revision you just committed in the trunk
• deploy on the concerned environments with a SVN update
• rename the branch so that it’s made clear it won’t be used anymore (“/branches/obsolete-feature-faq-development”)
• eventually, delete the branch after a while

Extra resources:

• Subversion Best Practices

Reference:
http://blog.jmfeurprier.com/2010/02/08/svn-trunk-branches-and-tags/