Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News Microsoft’s Branching and Merging Guidelines

Microsoft’s Branching and Merging Guidelines

Leia em Português

This item in japanese

Microsoft has released a draft of their new Branching and Merging Guide. While ostensibly meant for TFS users, much of the advice is applicable no matter which source control provider you choose. We begin with their basic topology.

Like most branching and merging guides, there is a main branch that serves as parent to all of the other branches. Known as the “trunk” to many, Microsoft refers to it as MAIN. There are two principal sets of branches coming off of MAIN, known as DEVELOPMENT and RELEASE.

The initial guidance for the development branches are fairly light, as it often comes down to how your company organizes its teams and features. One specific recommendation remains from previous versions of the guide, Microsoft continues to advocate not incrementing version numbers in development branches. The theory is that if you only increment the version number in the main branch you can tell at a glance how long it has been since the development branch was last re-synced with its parent.

For the release branches, Microsoft offers several options. The simplest is to just have a branch literally called “RELEASE”. They call this their “basic plan” and it makes sense for continuous deployment scenarios where you don’t need to work on more than one version at a time.

If you support multiple versions of an application, and those versions are occasionally updated via service packs then they recommend what they call the “standard plan”. Under this plan a service pack branch is created for each major release. At the same time, the actual release branch is created from its service pack branch and is marked read-only. Since the branch is read-only, it is also useful when compliance requirements necessitate a true and accurate snapshot of production being maintained.

When necessary, emergency hotfixes can be applied to directly to the release branch and then migrate back to the main branch. However, if hotfixes are a regular occurrence then it may be preferable to create a separate branch specifically for them. This document explains how that extra branch will change your workflows in the section titled “Advanced Branch Plan”.

The final release-side branching strategy discussed in Microsoft’s guide is the “Code Promotion Plan”. This plan does away with the idea of individual development and release branches. Instead developers work entirely in main, pushing updated to the test branch whenever they feel the code is stable enough. Code in the test branch is then promoted to the production branch when it is deemed ready.

While there is a philosophical difference between this and the basic plan, as far as implementation is concerned there really isn’t really much difference.

The rest of the chapter discusses options for dealing with branching by feature. The techniques outlined there work equally well with any of the above strategies for handling releases.

Local vs Server Workspaces

Many of the complaints about TFS revolve around the way it expects to always have a server connection. As it turns out, there is a good reason for this. TFS was designed primarily to deal with Microsoft’s development problems:

  • Very large codebases (5+ million files per branch, with an average use of 100,000 to 200,000 of those files per developer)
  • Distributed, global development teams working over relatively poor connections (300 kbps or less)

Clearly TFS is superior to a decentralized VCS when you need to create a branch that contains 5 million files, trying to download the chance history for that many files across every branch is just plain ridiculous.

However most development teams don’t work like that. Even the Linux kernel only had 9.2 million lines of code (circa 2007-2008) and most projects don’t come close to that figure. Furthermore, TFS assumes that you have an always-on connection and everything you do will be through the server.

TFS 11 changes that by introducing local workspaces. Also known as “Subversion style”, this mode addresses many of the complaints.

  • Files are not read-only. You can edit them at will. They are automatically detected as “checked out” when you edit them.
  • If you create new files, Team Foundation Server will detect them and enable you to add them to your project.
  • If you delete them locally, Team Foundation Server will notice and give you the option of either deleting them from Team Foundation Server or restoring the local copy from the server.
  • One of the nicest implications is that you no longer need to use a tool with version control integration for the right thing to happen (because the file system is the master so you can use Notepad or any other tool and Team Foundation Server will work the way you’d expect. The local copy is the master and Team Foundation Server appropriately handles the changes.

Note: For those who prefer a DVCS style workflow (e.g. git) will have to wait for TFS 12.

Managing Shared Resources in Team Foundation Server

The final section in this draft deals with options for managing shared resources. With Visual SourceSafe shared resources were actually quite easy to deal with. One could simply create links between folders such that “$\projects-a\bin\commons” and “$\commons” were literally the same folder. And if necessary, a single command could break this relationship.

TFS does not have this capability, so instead you have to choose one of three options:

  • Duplicate the shared files in each branch. This provides isolation at the expense of wasted disc space.
  • Keep a separate shared folder outside of the branches. This is referenced using hint paths in the project, a technique that can be error prone and only works for assemblies.
  • Use workspace mapping to make the shared folder appear to be under each branch on the local hard drive. This is more versatile than hint paths, but requires each developer to make the same mapping.

The tradeoffs and workflows for each are detailed in the guide.


It should be noted that these recommendations are being developed in a collaborative fashion. Microsoft is actively soliciting feedback on the TFS Branching and Merging Guide CodePlex site. Tens of thousands of development teams are expected to read this guide, so if you disagree with any of their advice now is the time to let them know.

Rate this Article