Professional Documents
Culture Documents
TFS Branching Guide Scenarios 2010 v1
TFS Branching Guide Scenarios 2010 v1
VSTS Rangers This content was created in a VSTS Ranger project. VSTS Rangers is a special group with members from the VSTS Product Team and Microsoft Services. Their mission is to provide out of band solutions for missing features or guidance.
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication. This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT. Microsoft grants you a license to this document under the terms of the Creative Commons Attribution 3.0 License. All other rights are reserved. 2011 Microsoft Corporation. Microsoft, Active Directory, Excel, Internet Explorer, SQL Server, Visual Studio, and Windows are trademarks of the Microsoft group of companies. All other trademarks are property of their respective owners.
Contents
Scenarios Overview: Scenario #1: Single Team Branching Model Scenario Overview: Single Team Branching Model Branch Definitions for this scenario: Scenario Walkthrough: Structure in Team Foundation Server Scenario Source Control Artifacts: Scenario #2: Concurrent Hotfix, Service Pack, and v.Next Scenario Overview: Concurrent Hotfix, Service Pack, and v.Next Branch Definitions for this scenario: Scenario Walkthrough: Structure in Team Foundation Server Scenario Source Control Artifacts: Important Scenario Considerations: Scenario #3: Branching and Labeling Scenario Scenario Overview: Branching with Labels Branch Definitions for this scenario: Scenario Walkthrough: Structure in Team Foundation Server Scenario Source Control Artifacts: Important Scenario Considerations: Environment and Build Location Considerations for Scenarios Environment to Branching Structure Mapping 4 6 6 6 7 7 8 11 11 11 13 14 15 16 18 18 18 19 20 20 22 23 24
Scenarios Overview:
These scenarios provide examples of common situations that development teams find themselves in and offer specific branching patterns to address those situations. One of the most frequent challenges faced by development organizations is when different teams need to work in parallel, or need to have a subset of the team work in isolation. These scenarios should allow teams to quickly understand various branching options available to them. The scenarios should provide the necessary framework for a team to adopt a branching structure to addresses their needs. Its important to note that while these scenarios present one valid solution to a specific situation, it is possible and often likely that there are alternative approaches that are also valid. Each scenario describes both the layout of the source structure and hierarchy of the branching structure. While the file structure and branching structure of most development teams is complex, re-occurring branching patterns routinely present themselves and we hope that the scenarios presented here help answer the questions of when to branch, what to branch, and the value branching provides to help development efforts be faster and smoother. In each scenario, a situation is presented that a hypothetical development team at Wood Grove Banking is facing. The recommended branching structure as well as the branching and merging process will be explored and examined in detail. Before exploring each scenario, its important to understand branching within the broader context of Source Control Management (SCM). Branching enables parallel development and build automation by providing multiple development phases (for example bug fix, new feature development, stabilization of code, etc.) with their own self-contained isolation work area of needed source codes, external dependent components and a stable build environment. Source Control Management typically involves: Branching source code to create an isolated area based on a stable or milestone state of source code (such as the last successful build). During a branch operation, the source branch (where the code is taken from) is called the parent branch and target branch (the resulting code copy) is the child branch. Within a branch, developers can make code changes, which can be contained (isolated) and stabilized separately from other branches. Developers can perform bi-directional merging of changes between two branches that share a parent/child relationship. Merging from a parent branch to a child branch is called forward integration. Merging from a child branch to a parent branch is called reverse integration. On occasion, a merge can be made between two branches that do not have a merge relationship (such as parent/child branch relationship). Such a merge is called a baseless merge. A baseless merge creates a merge relationship between the source and target branches. In each of the VSTS Rangers branching plans, we start with a Main branch. The main branch is intended to be a stable code base. Development branches are full child branches of Main. We recommend frequently synchronizing the Main branch with each of the child Development branches. This is accomplished by doing regular forward integration (FI) merges from the Main branch to its child Development branches. 4
On the other hand, we recommend only doing reverse integration (merging code from a child Development branch back to the Main branch) when the code in the source branch is stable and has passed Quality Assurance (QA) quality gates. Keeping the Main branch synchronized with the Development branches helps avoid the big bang merge problem, where many changes from the Main branch are merged into a child Development branch causing many merge conflicts that must be resolved before completing the merge. Often when changes are made to a file in the source branch of a merge, they can be automatically merged with the corresponding file in the target branch. Merge conflicts arise when changes are made to the same file in both the source and target branches involved in merge. Often, when these changes are in different sections of the file, these merge conflicts can be resolved automatically by the tool (AutoMerge). Sometimes the person doing the merge may know to override the target file (take from source) or to ignore the source (keeping the target version). There are times, however, where resolving merge conflicts requires manual intervention. In these situations, TFS will display a three-way merge conflict resolution window showing the conflicting change. The user can view the code in the source file, the target file, and the resulting merged file. In Visual Studio 2010, conflict resolution is now a non-modal operation. From here the user can select specific lines of code from the target or source files (or both) to be merged into the final result.
Code in the MAIN branch is labeled with a version number and a build number that is incremented with each build of MAIN. Code in the DEV branch inherits the version and builds numbers from the MAIN branch. When code is built in the DEV branch, it is labeled with a timestamp. Comparing the version and build number from MAIN with the build and version number in DEV is one way to easily determine how much time has passed since the MAIN branch was synced with the DEV branch. At frequent intervals code from the MAIN branch should be merged (forward integration - FI) branch to the DEV branch This enables changes that might take place in the MAIN branch to be merged (integrated with) ongoing development in the DEV branch. During development, the DEV branch should be running Continuous Integration (CI) builds while the MAIN branch does nightly builds. The CI builds in the DEV Branch allow for the team to quickly fix any code changes that might have broken the development branch. At some specified point in time, when the DEV branch meets certain quality gates (for example number of outstanding bugs), it is ready to be put into production. At this point, the DEV Branch is merged (Reverse Integration -RI) into the MAIN branch. Just prior to merging (RI) DEV with MAIN, one final merge (FI) is done from MAIN to DEV. The goal is to test the integration of MAIN with DEV in the DEV branch, keeping MAIN as stable as possible.
Scenario Walkthrough:
1. Create a folder named MAIN with a subfolder Src. 2. Check-in these changes. 3. Select the MAIN folder and convert this folder into a branch (File | Source Control | Branching and Merging | Convert Folder to Branch) 4. Create the DEV branch from MAIN (File | Source Control | Branching and Merging | Branch) 5. The initial source code that (for example Release 1.0) is checked into TFS in the MAIN branch. 6. The MAIN branch is labeled with V1.0. 7. A DEV branch is created from the MAIN branch and labeled V1.1 $/WoodGroveBanking/Main/ to $/WoodGroveBanking/DEV 8. The MAIN branch is merged (FI) into the DEV branch at regular intervals. 9. Certain quality standards have been met the DEV branch is reverse integrated into MAIN $/WoodGroveBanking/DEV to $/ WoodGroveBanking/Main/ 10. The MAIN branch is now labeled V1.1 11. The DEV branch is labeled V1.2 and development continues forward.
10
are reduced merge conflicts, these 2 considerations are important because time shouldnt be spent reengineering solutions or spending lengthy cycles resolving complex merges. The Windows development team at Microsoft has a comprehensive branching structure in place that provides the ability to work concurrently on Hotfixes, service packs, and future releases. The Windows development team has a branching plan that precisely defines the ways that code leaves the organization and ends up in the hands of its customers. A simplified overview of the Windows branching structure involves a minimum of 3 different release vehicles: Major Release (RTM) Hotfixes for a Major Release Service Packs for the Major Release Within each of these 3 release vehicles there are separate branch plans that enable code to be checked in once and then merged back to main. From development to main there should be regular forward (FI - parent to child) and reverse (RI - child to parent) integrations. The regular FI and RI integration ensure that the entire organization has a clear understanding of the structuring of the application and is aware of dependencies between various development efforts. Once the code in main has reached some objective measure of release quality (e.g. bug count, test pass %, preview feedback, etc.) then it is time to create the production/release branch for this release. The key to this branch plan is that the SP, Hotfix and RTM branches must be created in order to assure the parent child branch relationships are maintained. Without enforcing the integrity of these branch relationships, the organization cannot begin to address regressions or merge conflicts. For an organization looking to be able to work concurrently on releases there should be a strong association between the branching structure and the release vehicles so that the entire organization is aligned on very specific releases and in ensuring the associations it is possible to identify work that is not focused around a particular release.
12
Scenario Walkthrough:
1. 2. The initial source code is checked into TFS in the [Main] Branch Two Development branches are created with the relevant team branches from [Main]. The first branch is: $/WoodGroveBanking/Dev/Dev_Team1 The second branch is: $/WoodGroveBanking/Dev/Dev_Team2 The organization intends to create one or more service packs (collections of cumulative bug fixes) for the application, so a ServicePack Branch is created under the Production Branch. $/ WoodGroveBanking/Main/ to $/WoodGroveBanking/Production/V1/ServicePack The organization has to have the ability to ship immediate fixes and still be able to integrate all Hotfixes into the next cumulative release without having any regressions so a child Branch for Hotfixes is created under Service Pack. $/WoodGroveBanking/Production/V1/ServicePack to $/WoodGroveBanking/Production/V1/Hotfix The organization wants to ensure that once code reaches some objective measure that a release branch is created so a child Branch for the RTM version is created from the Hotfix branch. $/WoodGroveBanking/Production/V1/Hotfix to $/WoodGroveBanking/Production/V1/RTM The organization also has begun work on the next version of the product, V2, so a child Branch is created from Main for V2. $/ WoodGroveBanking/Main/ to $/WoodGroveBanking/Production/V2/ServicePack At the onset of the V2 release the organization knows that at some point after V2 has shipped they will ship a service pack that will contain all Hotfixes so the branching structure is identical to V1 and a child Branch for Hotfixes is created under Service Pack. $/WoodGroveBanking/Production/V2/ServicePack to $/WoodGroveBanking/Production/V2/Hotfix The V2 release will take considerable time to be developed and tested but at some point in the future a child Branch for the RTM version is created from the Hotfix branch. $/WoodGroveBanking/Production/V2/Hotfix to $/WoodGroveBanking/Production/V2/RTM 13
3.
4.
5.
6.
7.
8.
14
15
Changes should be merged (RI) in from RTM->HF->SP->Main only. This will ensure future releases are regression free as fixes will integrate into the next cumulative release (i.e. all Hotfixes will be merged into the next service pack). Do not FI changes from main to the Service Pack after the initial release branches are created. An exception may be for merge specific change sets as needed for a Hotfix or Service Pack release.
17
Scenario Walkthrough:
1. The initial source code is checked into TFS in the [Main] Branch 2. A Dev Branch is created with the relevant team branches from [Main]. The first branch is: $/WoodGroveBanking/Dev/Dev_Team1 The second branch is: $/WoodGroveBanking/Dev/Dev_Team2 3. Team1 reaches the first milestone and labels the contents of their branch Dev_Team1 with label V1.1 4. Team2 reaches the second milestone and labels the contents of their branch Dev_Team2 with label V1.2 5. Dev_Team1 branches by label into the Test Branch in order to allow QA to test their teams work. Branch by label using the V1.1 Label $/WoodGroveBanking/Dev/Dev_Team1 to $/WoodGroveBanking/Test/V1.1 6. Dev_Team2 branches by label into the Test Branch in order to allow QA to test their teams work. Branch by label using the V.1.2 Label $/WoodGroveBanking/Dev/Dev_Team2 to $/WoodGroveBanking/Test/V1.2
19
20
21
22
23
Test
UAT
Usually MAIN, sometimes PRODUCTION when previewing a software release that needs to pass UAT. PRODUCTION
Staging/Pre-Production
Production
PRODUCTION
24