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

Having to keep these library files up-to-date with official patches and improvements sounded like a full-time job.
This solution sucked.
A lot.

We are programmers, and we really hate repetitive tasks because we are lazy. We spend most of our time building applications which automate human tasks, why not take care of this one?

Good news, a quick googling revealed our issue was a common one, and there was already a ready-to-use solution: SVN externals.

What are SVN externals?

SVN externals allow to include (nest) a remote SVN repository into another SVN repository. They are set through SVN properties.

How to use them?

If you’re a command-line geek, type:

svn propset svn:externals "http://svn.3rdapp.com/super-library/ library" .

This will create a SVN property at the current location (don’t miss the final dot “.” at the end) named “svn:externals”, and its value will be “http://svn.3rdapp.com/super-library/ library”. Which means: insert a directory named “library”, which will retrieve its content from a distant SVN repository located at “http://svn.3rdapp.com/super-library/”. The next time you run a SVN-update, the third-party files will be added to your SVN project.

You can do the same with TortoiseSVN Windows Shell Extension for Subversion: right-click when browsing your SVN project with the Windows file explorer, highlight “TortoiseSVN”, then click “Properties”:

Now, click “New…”, type or pick “svn:externals” in the “Property name:” drop-down, then type “http://svn.3rdapp.com/super-library/ library” in the “Property value:” textarea. Click “OK” twice:

Now, every time a new version of the third-party application will be released, it will be reflected when you SVN-update your local copy of your project.

• mathematical functions:

function SomeMaths($x)
{
	return $x + pow($x, 3.2) - cos($x);
}

• functions which retrieve content from a file:

function GetConfiguration()
{
	return parse_ini_file('configuration.ini');
}

• functions which retrieve content from a database:

function GetArticleById($id)
{
	$sqlId  = mysql_real_escape_string($id);
	$result = mysql_query("SELECT `id`, `title` FROM `article` WHERE `id` = '$sqlId' LIMIT 1");

	if (FALSE === $result)
	{
		throw new Exception('Query failed.');
	}

	return mysql_fetch_assoc($result);
}

If your project holds a function like one of these, and:

• your prefered profiling tool reveals that a lot of the execution time is spent in this function
• its returned value is always the same during a single run (script execution), when providing the same arguments
• this function is called more than once per run

Then consider caching (saving) its return values.

Here is how it can be achieved (yes, there are more advanced techniques to do it, but this is not the point of this post): add a static variable in the body of the function, which will hold an associative array, mapping every parameter combination with a return value:

function GetArticleById($id)
{
	static $cache = array();

	// Return value is not in cache yet?
	if (!isset($cache[$id]))
	{
		$sqlId  = mysql_real_escape_string($id);
		$result = mysql_query("SELECT `id`, `title` FROM `article` WHERE `id` = '$sqlId' LIMIT 1");

		if (FALSE === $result)
		{
			throw new Exception('Query failed.');
		}

		// Add return value to cache
		$cache[$id] = mysql_fetch_assoc($result);
	}

	// Return cache content
	return $cache[$id];
}

Here it is, the (possibly heavy) process of querying the database will only be executed once at the first function call. Every other function call with the same argument will use the cached return value.

Keep in mind that the amount of cached return values must be reasonable (available memory is limited). If there are millions of possible arguments combinations for a function in a single run, you’ll have to consider a more elaborate way of optimizing it (this could be the subject of a future post).

Also, always, always, ALWAYS profile your code BEFORE you decide to apply an optimization like this one (and wait for your project to be nearly completed before profiling).