Version control systems are wonderful tools and terrible tools all depending on the process used to manage the files stored in them. They allow tracking changes, updates, reversing updates, comparing to older updates, and creating multiple branches and variations of files ad-infinitum. What are good rules to keep good tools from going bad?
Rule #1 Don’t Break The Base
Don’t check code in that breaks the trunk code base.
Organizations generally follow two philosophies for code check-ins: Check-in daily under penalty; or Don’t break the base.
Check-in daily under penalty as a philosophy is problematic because developers are forced to check code in that may or may not compile. Organizations use this as a backup mechanism, but it’s a poor solution for that approach.
Don’t break the base as a philosophy can cause headaches because a developer may go long periods of time (days/weeks) with multiple code changes and then they loose the benefits of rolling back stuff to a level of code that was checked in. This weakness can be resolved by adding a scratch area in a source control system that developers can use daily / hourly that is not part of the main code base structure. Once developers are confident it won’t break the base, they can check in to the main trunk without causing others problems. I don’t like two places for the same thing, but in practice, the scratch area works well and is often used sparingly. Labels and branches are not good for scratch work.
The most common break the base problem isn’t really code that doesn’t compile, it’s missing files. Files that were on the developers machine, but weren’t checked in. Having a tool like Sourcegear Vault that shows files on the disk that haven’t been added make this problem much less likely to occur. Before my teams used Sourcegear, this problem happened a lot. It still happens (even to me), but much less frequently than in the past.
Rule #2 Label Your Releases
Label all releases (both internal and external).
Labels are like breadcrumbs. They can be applied to a common root directory and all subsequent child folders and files get the same label. Adding labels when releases are made allow you to go back and cut a branch from a label later if needed, or to pull the source for that particular label.
I like labels in the form “Rel 2.0.3.0 2009 12 03”. This includes the release number, and the date the release was made. Adding the date might be redundant because most source control systems keep the date a label is made, but not all tools show the date unless you ask them to. Making it part of the label makes it easy to find two pieces of information in one quick scan.
In some projects I’ve even used the only build from a label approach. While extremely rigid, it works when teams are franticly checking in code, and a build machine is used to specifically create daily builds. If it’s a manual process, this rarely works reliably. If the label / get / build process is automated, then it has better success.
Rule #3 Prune Your Branches
Anytime a branch is created, it should be pruned (after 30,60,90,180 days) and folded back into the trunk.
Source control branches give the illusion of control. They are generally good for two things:
- Marking a point in the code for generating an emergency hot fix for a customer.
- Marking a point in time for a base to be used when migrating to another platform or architecture.
Branches are problematic because they create multiple places for people to put things (and subsequently get lost) and they also create multiple places for people to get things (and subsequently inadvertently get the wrong version that was desired). I’ve learned to try to avoid branches if at all possible. Multiple source control branches add expense and time, but don’t add a lot of value.
Branches are complex for source control software to implement. They often have issues (not so much as software issues, but issues with documentation on how to make the source control system achieve the behavior you want). If your running SourceSafe and try branches, you are sadistic. Upgrade to a real source control system like Sourcegear Vault or PVCS (Dimensions, Merrant, Intersolve, Serena or the current PVCS product name of the day). I’ve reviewed CVS and Subversion, but the architecture and features of the rich clients for Sourcegear Vault wins hands down despite having to pay a license for each user to use them (although Sourcegear is free for one user).
In my experience, Sourcegear Vault is the only tool that has an architecture that allows smart clients and a central web service that works well over the internet for multiple teams in multiple locations. All other solutions I’ve evaluated including Microsoft Visual Studio Team Foundation, require significant investment in hardware and only work well over a LAN. These solutions were designed with thick client / server solutions for LANS, not WANS or the Internet. I have teams in India, California, Oklahoma, and Raleigh that have used a common Vault solution for over five years and it’s worked flawlessly along side Visual Studio (2003, 2005, 2008, 2010).
Rule #4 Properly Dispose Of Flags
Anytime a code feature flag is created, it should be reviewed to see if it’s still applicable (after 90, 180, 360 days). Flags that are no longer applicable should be removed to simplify the code base.
Just like taking care of national or state flags with flag etiquette or the flag code code flags should be evaluated, cleaned up and removed when they aren’t needed anymore. A code base will be encumbered by the weight of too many flags.
The Flickr developer blog posted a long running practice of mine and common technique at Flipping Out on the topic of code flags.
if (flag)
{
// New Feature
}
else
{
// Existing Behavior
}
The downside of this approach is that if flags are never removed, it becomes increasingly difficult or impossible to add new features in sections of conditional code. It can also be tedious to add the flags and the code, but if it’s practiced, this problem is usually overcome quickly, becoming second nature. The upside of this approach is it helps significantly with Rule #1 Don’t Break The Base. Just make sure the default is set so the flag is off unless specifically turned on.
For the OCD flagger, having flags at the system level, per account instance, or per user level give ample opportunity for this approach. Perhaps best used sparingly, but code flags are best used when needed and are simpler than branches to deal with.