Branching Guidance – Branching for Development

I recently had a series of email exchanges with a person who was trying to advise his customer on a branching plan. As part of this exchange I offered the following discussion on Branching for Development.

I often like to separate the discussion of the development branch plan and the release branch plan. If you notice, all three plans described in the Rangers Branching Guidance II differ primarily on the release side and not on the development side.

On the development side, all three branching plans in the guidance show the same structure (a single DEVELOPMENT branch with MAIN as the parent). If you look at the Scenarios 2.0 document, specifically at Scenario #2, you will see guidance for creating multiple development branches. Sometimes these branches (DEV-1, DEV-2, and DEV-n) are characterized as feature team development branches. You will note that all of the feature branches are full branches of MAIN. A key question then is: “When should Dev Team branches be full branches of MAIN, and when is it appropriate to have an intermediate DEVELOPMENT branch. There are several (often) competing goals here. One is to have the MAIN branch be as stable as possible. A second is to reduce the depth of the branch structure. A third is to maximize code velocity.

Here I attempt to address these three competing goals. To keep MAIN stable, it is important not to merge changes into MAIN, such that the integration of these changes happens for the first time in MAIN. One way that people attempt to achieve this goal is to have this intermediate DEVELOPMENT branch between MAIN and the DEV-1, DEV-2, DEV-n feature team branches. The challenge this introduces is that when a new level of branching is introduced it increases the need for Merging and Testing. Merging, especially on larger and more complex projects, can be significantly challenging as each merge conflict needs to be resolved, often manually. This is one reason for the stated goal to reduce the depth of the branch structure - by not introducing the intermediate DEVELOPMENT branch in the first place.

If you only have MAIN and a DEV branches, where does integration of changes made by different feature teams happen? The Rangers Branching Guidance II recommends doing frequent Forward Integrations from MAIN to the DEV Feature branches. The longer you go between these FI integrations, the more the DEV branches get out of sync with MAIN. This means that when you eventually merge a DEV branch with the MAIN branch, it can be a long, time-consuming process to complete the merge. If you simply merge DEV into MAIN without first merging possible changes from MAIN into DEV, then the integration of these changes affects the stability of the MAIN branch. Whenever you merge MAIN into a DEV branch, you have should test the integration of changes in a DEV branch before moving these changes down into the MAIN branch. As a result, MAIN remains more stable, but the DEV branch activity is slowed down while the integration of changes is tested. This impacts the third goal, maximize code velocity.

Do you solve this code velocity problem in the Feature Team branches by introducing an intermediate DEVELOPMENT branch between the MAIN branch and the Feature team branches? Can you solve this another way? In my view, using automated testing, especially Build Verification Testing, helps reduce the impact of frequent merges on code velocity in the DEV branches, while at the same time reducing the overall depth of branches (and hence the resulting merge, conflict resolution, and integration testing). All while keeping the MAIN as stable as possible. If you do not have automated testing available, then you might consider introducing the intermediate DEVELOPMENT branch, so as to not impact DEV code velocity or MAIN stability while you do the merging, conflict resolution, and integration testing (in DEVELOPMENT).

To summarize, VSTS Rangers often recommend a two-level logical branch structure on the development side. As for the physical structure, you can have additional containers (folders) holding multiple branches. For example, when you have multiple DEV feature branches, you can organize these into a Development container (or Features container as your physical branch structure below seems to depict).

In the Basic Branch plan, as with all of the plans in the VSTS Rangers Branching Guidance II main document, development happens in the (or a) DEV branch. Changes are checked-in to the DEV branch. MAIN is frequently merged (FI) into the DEV branch(es) where merge conflicts are resolved, integration is tested, etc. Then when you get to the point where a feature is complete and meets previously determined quality standards, the feature is merged (RI) down into MAIN. Immediately before doing this you would do one last FI from MAIN into the DEV branch, resolve all problems and then RI DEV to MAIN.