Branch at a High Level, Including Configuration and Source Files

- J.D. Meier, Jason Taylor, Alex Mackman, Prashant Bansode

Branch at a high-enough level that the branch you create is still compilable. For instance, in the following source tree:
  • Main – container for all assets you need to ship the product
  • Source – container for everything you need to build
    • Code – container for source code
    • Shared Code – container for source code that is shared from other projects
    • Unit Tests – container for unit tests
    • Lib – container for binary dependencies
  • Docs – container for documentation that will ship with the product
  • Installer – container for installer source code and binaries
  • Tests – container for test team test cases

Branch at the level of the Source folder to ensure that the new branch contains all source and configuration files.

Additional Resources

Last edited Jul 26, 2007 at 9:15 AM by prashantbansode, version 4


RichardBerg Apr 11, 2007 at 12:30 PM 
Comments sure look ugly when you strip out all the whitespace @_@

RichardBerg Apr 11, 2007 at 12:30 PM 
This is a great point. I'm not sure it's widely grasped, especially when people are coming from SCM systems that branch in version space. When you branch in path space as we do, paths become very important. (gee, it sounds obvious when you say it :) )

When I answer this on the forums I use even stronger language. For example: "...always branch high enough in the tree that you can build your entire product. This ensures that you can always recreate a configuration without having to setup special workspace mappings; anyone can just download a branch and build it. TFS stores branches efficiently -- the project code that's the same between branches won't take up extra space." In short, branching too low in the tree (e.g. at "Code" above) has lots of potential pitfalls with no real advantages.

I glossed over said pitfalls in my forum post; let's spell it out here. Shared components are happiest when the relative path between them stays constant. When relative paths are allowed to be flexible, you end up with build systems that work on certain machines (or in certain configurations) but not others. When you create a branch in a path-space system like TFS, all the paths underneath the branch root are mirrored exactly. Above the branch root, anything goes. There's no guarantee the new branch will be rooted as a peer of its parent. Nor do you have any control over the path structure of items that were not branched. Working around these quirks is easy for an individual -- assuming our Edit Workspace dialog is doing its job, anyway. However, relying on such workarounds at an institutional level is asking for trouble.

Inclusive branches also offer insight into your larger branch strategy. Let's say Adam and Bob anticipate they'll need to work with different versions of some external SDK simultaneously. Experienced SCM gurus will recognize it as a sign their project needs to employ the Branch For Isolation pattern and that Adam and Bob should end up working in separate branches. However, if you've already adopted our practice of adding literally all prerequisites to a branch -- compilers, the C runtime, the .net framework, SDKs, random tools, the works -- then you don't need to be a guru. Adam and Bob cannot work in the same branch because their branch and their toolset are synonymous. We've forced your hand (in a good way).