Académique Documents
Professionnel Documents
Culture Documents
Microsoft Visual Studio Team Foundation Server Branching Guidance 2010 Main
Bijan Javidi, James Pickell, Bill Heys, Tina Erwee, Willy-Peter Schaub Microsoft Corporation
Visual Studio ALM Rangers This content was created in a Ranger project. Visual Studio ALM Rangers is a special group with members from the Visual Studio Product Team, Microsoft Services, and Visual Studio ALM MVPs. Their mission is to provide out of band solutions for missing features or guidance.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
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.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
Table of Contents
Table of Figures ............................................................................................................................................. 5 Introduction .................................................................................................................................................. 6 Vocabulary ................................................................................................................................................ 7 Branch Plan quick start .............................................................................................................................. 7 Basic Branch Plan ...................................................................................................................................... 8 Standard Branch Plan.............................................................................................................................. 12 Advanced Branch Plan ............................................................................................................................ 15 Mature Branch Plan ................................................................................................................................ 19 About versioning ..................................................................................................................................... 22 All I need is MAIN ................................................................................................................................. 23 DEVELOPMENT Branches ............................................................................................................................ 23 Multiple Development Branches ............................................................................................................ 24 Breaking changes ................................................................................................................................ 24 Segregated Feature Work ................................................................................................................... 24 Next Version development ................................................................................................................. 25 Scratch or temporary branches ....................................................................................................... 26 RELEASE Branches ....................................................................................................................................... 26 Integrations ................................................................................................................................................. 28 Build Quality ................................................................................................................................................ 28 TFS 2010 Branch and Merge Permissions ................................................................................................... 28 Manage Branch Permission ................................................................................................................ 29 Merge Permission ............................................................................................................................... 29 Change History and Visualizing Changesets................................................................................................ 29 Branch Re-parenting ................................................................................................................................... 30 Conclusion ................................................................................................................................................... 30
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
Table of Figures
Figure 1. Basic Branch Plan ........................................................................................................................... 8 Figure 2. Basic Branch Plan - Branch Hierarchy Visualization ....................................................................... 8 Figure 3. Basic Branch Plan - Folder and Branch Structure........................................................................... 9 Figure 4. Basic Branch Plan - Main Branch Relationships ............................................................................. 9 Figure 5. Basic Branch Plan Visualizing a Changeset Hierarchy View ................................................... 10 Figure 6. Basic Branch Plan - Visualizing a Changeset - Timeline View....................................................... 10 Figure 7. Standard Branch Plan ................................................................................................................... 12 Figure 8. Standard Branch Plan - Branch Hierarchy Visualization .............................................................. 12 Figure 9. Standard Branch Plan - Folder and Branch structure .................................................................. 13 Figure 10. Standard Branch Plan Visualizing a Changeset Hierarchy View ........................................... 13 Figure 11. Standard Branch Plan Visualizing a Changeset Hierarchy View ........................................... 14 Figure 12. Advanced Branch Plan ............................................................................................................... 15 Figure 13. Advanced Branch Plan - Branch Hierarchy Visualization ........................................................... 15 Figure 14. Advanced Branch Plan - File and Branch structure .................................................................... 16 Figure 15. Advanced Branch Plan Visualizing a Changeset Hierarchy View.......................................... 16 Figure 16. Advanced Branch Plan Visualizing a Changeset Timeline View ........................................... 17 Figure 17. Mature Branch Plan ................................................................................................................... 19 Figure 18. Mature Branch Plan - Branch Hierarchy Visualization ............................................................... 19 Figure 19. Mature Branch Plan - Folder and Branch Structure................................................................... 20 Figure 20. Mature Branch Plan - Visualizing a Changeset Hierarchy View .............................................. 20 Figure 21. Mature Branch Plan - Visualizing a Changeset Timeline View ................................................ 21 Figure 22. Release Branches ....................................................................................................................... 27
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
Introduction
Welcome to the Microsoft Visual Studio (VS) 2010 Team Foundation Server (TFS) Branching Guide! Since the original release of this guidance in 2007 weve received many encouraging messages confirming the usefulness of this guide in planning, executing and maintaining branches, in allowing TFS users to devise, execute and maintain their branch plans. Using feedback from users, we, a team of Microsoft Visual Studio ALM Most Valuable Professionals (MVPs) and Microsoft Services consultants have refreshed the guidance presented in the original document produced as part of a Ranger project. While some of the original document has been retained, you will notice 3 new themes through the guide. This guide targets the Microsoft 200-300 level users of TFS. The target group is considered as intermediate to advanced users of TFS and has in-depth understanding of the product features in a realworld environment. Parts of this guide may be useful to the TFS novices and experts but users at these skill levels are not the focus of this content. Before executing on your branch plan, pay attention to this cautionary message - every branch you create does have a cost so make sure you get some value from it. The mechanics of branching in TFS are simplified to a single right-click Branching and Merging | Branch command. However, the total cost of branching is paid by reduced code velocity to MAIN. Merge conflicts, and additional testing can be expensive. Throughout this guidance we ask users to confirm that a branch is really needed and always ask the question How does this branch support my development project? Readers can casually think of this as the branch ROI. This is not a firm metric that we can collect; rather a general question that should be asked before creating a branch. By justifying each branch in terms of required level of isolation for development or release activity, we hope to avoid situations where this guidance was assumed to be an off the shelf solution and an unnecessarily complex branch plan was created. Once you begin thinking of branches in terms of cost and benefit we hope most teams will find a productive middle ground that gives them the right amount of branching to achieve their business goals. Branching and merging of software is a very large topic. It is an area where there is a lot of maturity in the software industry. This document focuses on applied and practical examples of branching that you can use right now. We purposely avoid any academic discussion on the topic of branching and focus on patterns that work for the majority of business cases we have seen. Our hope is that this guide covers the majority of our customer branching needs. In addition to this guide you will find separate branching scenarios, Q&A, tutorials and updated branch diagrams that will grow over time to include additional edge cases. We encourage ongoing contributions from our user community to submit ideas for new Scenarios that we will add to these packages. These new packages that will become available on Codeplex will be refreshed based on user feedback.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
Vocabulary
This guide uses common vocabulary and general categories to group work and where check-ins are made. Language may vary in your organization so some translation may be required. DEVELOPMENT branches changes for next version work. MAIN branch This branch is the junction branch between the development and release branches. This branch should represent a stable snapshot of the product that can be shared with QA or external teams. SERVICE PACK (SP) A collection of Hotfixes and features targeting a previous product release. HOTFIX A change to fix a specific customer-blocking bug or service disruption. RELEASE branch A branch where ship stopping bug fixes are made before major product release. After product release this branch usually becomes read-only. FORWARD INTEGRATE (FI) merges from parent to child branches. REVERSE INTEGRATE (RI) merges from child to parent branches. RELEASE VEHICLE How your product gets to your customer (e.g. major release, Hotfixes and/or service packs).
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
The Basic branch plan will work well for your organization if you meet some of the following criteria:
1. 2. 3. You have a single major release that is shipped (i.e. a single release vehicle) to customers. Your servicing model is to have customers upgrade to the next major release. Any fixes shipped from the release branch will include all previous fixes from that branch.
10
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
b. Work in DEVELOPMENT branches can be isolated by feature, organization, or temporary collaboration. c. Each DEVELOPMENT branch should be a full branch of MAIN. way as MAIN. e. f. 2. Forward Integrate (Merge (FI) with each successful build of MAIN Reverse Integrate (RI) based on some objective team criteria (e.g. internal quality gates, end of sprint, etc.). RELEASE branch where you ship your major release from. a. RELEASE is a child branch of MAIN. permissions are set to read only. c. Changes from the RELEASE branch merge (RI) to MAIN. This merge is one way. Once the release branch is created MAIN may be taking changes for next version work not approved for the release branch d. Duplicate RELEASE branch plan for subsequent major releases. 3. Changes should be checked into one branch only a. All branches have a merge path back to MAIN. b. No need for baseless merges. b. Your major product releases from the RELEASE branch and then RELEASE branch access d. DEVELOPMENT branches should build and run Build Verification Tests (BVTs) the same
11
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
12
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
13
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
This plan will work well for your organization if you meet some of following criteria:
1. 2. 3. You have multiple ship vehicles (e.g. major release and additional service packs for that release). You want to enable concurrent development of service pack and next version products. You have any compliance requirements that require you to have an accurate snapshot of your sources at release time.
All of the guidance any key points from the Basic plan applies to the Standard plan. The Standard plan has these additional items to consider. RELEASE branches for release safekeeping and Service Pack work
1. 2. 3. 4. 5. 6. RELEASE tree (i.e. SP and RELEASE) are branched from MAIN at the same time to create MAINSPRELEASE parent/child relationship. Product releases from the RELEASE branch and then that branch is changed to read only. Servicing changes are checked into the Service Pack (SP) branch. Changes SP branches merge one-way to MAIN (SPMAIN). Ship stopping bug fixes checked into the release branch should merge back to MAIN through the SP branch (RELEASESPMAIN). Duplicate RELEASE tree plan for subsequent major releases.
14
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
15
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
16
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
All of the guidance and key points from the Basic and Standard plans apply to the Advanced plan. The Advanced plan has these additional items to consider.
1. RELEASE branches for release safekeeping, HOTFIX and Service Pack work a. RELEASE tree (i.e. SP, HOTFIX, and RELEASE) are branched from MAIN at the same time to create MAINSPHOTFIXRELEASE parent/child relationship. b. After creating the RELEASE tree make any final ship stopping bug fixes in the RELEASE branch. Produce the build you will release from the RELEASE branch. After product release update the access permission in the RELEASE branch to read only. This will ensure that you have the precise set of sources that made the shipping version of your product. c. Check-in based on which release the change applies to (e.g. Hotfixes are checked into the HOTFIX branch). Maintenance is expense so try to consolidate hot fixes for a single release in the HOTFIX branch associated with a particular release. If a customer specific hot fix is required then branch just that single component into a customer specific HOTFIX branch. A separate customer specific HOTFIX branch should be very unusual. d. e. Changes in HOTFIX and SP branches merge one-way through intermediate branches to MAIN (HOTFIXSPMAIN). Since hot fixes merge from the HOTFIX branch to the SP branch any release from SP would include all release hot fixes + any changes made directly in the SP branch. Note: if your release plan includes one or more service packs you may want to consider the mature branch plan presented later in the next section.
17
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
f. Duplicate RELEASE branch plan for subsequent major releases.
The plans above cover the majority of software development activities. Using these plans as a base will enable your teams to spend more time on developing high-quality code and assures that each branch has a specific role. The additional content below may help you determine where to deviate from the plan above.
18
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
19
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
20
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
21
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers MAIN Branch The MAIN branch is junction between development and RELEASE branches. Changes in the MAIN branch will merge (FI) into every DEVELOPMENT branch, so it is critical that builds from MAIN remain high quality. At minimum this means MAIN must remain buildable and pass all build verification tests Attributes of MAIN
Main should build daily to give the team a daily cadence to work toward. Every branch should have a natural merge (RI) path back to MAIN (i.e. no baseless merges). Breaks in MAIN need to be fixed immediately. No direct check-ins to MAIN branch; only build and BVT fixes. Successful MAIN build indicates child DEVELOPMENT branches should merge (FI) from MAIN. QA teams should be able to pick up any MAIN build for testing.
Code flow, the movement of changes between child and parent branches, is a concept all team members must consider. As the number of DEVELOPMENT branches increases, the need to merge (FI) following each successful MAIN build increases. Any DEVELOPMENT branch that is more than a couple days out of sync with MAIN is effectively working in the past.
About versioning
One strategy to keep track, at a glance, of how far out of sync a DEVELOPMENT branch is from MAIN is to increment the build number in MAIN only. When DEVELOPMENT branches are merged (Merge (FI) from MAIN they get the latest version resource from MAIN. If MAIN builds daily, its build number increments each day. Example: MAIN build 1.0.27.0 Dev_team1 build 1.0.25.0 The Dev_team1 branch has not merged (Merge (FI) to MAIN in 2 days if MAIN builds daily. Teams that adopt this strategy will frequently append a date-time stamp to the build number to prevent overwriting builds on the release share and provide clearer reporting since the DEV builds may keep the same build number for a few days.
22
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
DEVELOPMENT Branches
Your branch distance from main is equal to your level of insanity - anonymous Branching enables parallel development by providing each development activity for the current release its own self-contained snapshot of needed sources, tools, external dependencies and process automation. Such a self-contained snapshot effectively enables each development activity to proceed at its own pace, without taking any dependency on another. It follows that these snapshots are allowed to diverge their respective sources along the particular development activity they are involved with fixing a bug, implementing a feature, or stabilizing a breaking change. Before creating a DEVELOPMENT branch, make sure you can do the following:
Select a parent branch if your changes are focused on your next product release then the parent branch should be MAIN. Branch from a recent known good state of the parent start your branch from the latest successful build of the parent branch. There should be a label associated with the parent build that you can use as a starting point for your child branch. On day one of your DEVELOPMENT branch it should be in the same state as its parent (i.e. build and pass BVTs successfully). Merge (FI) frequently your goal should be to be no more than 1-2 days out of sync with MAIN. Ideally you should merge (FI) every time the parent branch builds and passes BVTs. Merge (RI) from child to parent based on quality. Minimum merge (RI) requirements are o o o Be in sync with parent branch Build successfully Pass BVTs
23
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
Segregated Feature Work Ideally teams can work in the same branch and still be productive. Finding defects as soon as possible is the mantra of many development methodologies. However, some teams, either due to their working style or for an engineering reason, may want to throttle when others have access to their particular feature.
24
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers The example here is the team wants the benefit of iterating and testing their feature but only wants to share functionality with other teams on some managed scheduled. One method for controlling when other teams have access to your feature work is through using a feature branch. A feature branch can be added at any time once you have, at least, the basic branch plan (i.e. DEV, MAIN, and RELEASE) in place. Usually the project will start work in a single development branch. When one team needs to control when other use their feature then a second development branch (i.e. a child of MAIN and peer of the original development branch) should be created. Before creating your Feature branch consider the following:
Branch the complete parent branch (usually Main) so the isolated feature can be built along with the other components. Merge (FI) frequently (ideally once a day or when there are successful builds from the parent branch) to make sure the isolated feature work remains compatible with the latest changes from the peer development teams. Make sure BVT coverage of other features is run in the feature branch. Ideally, if feature work in this branch is breaking another feature it will be caught and fixed in this branch before a merge (RI) to MAIN. A merge (RI) to MAIN is treated like a feature release to peer development teams. Once the feature branch merges (RI), other teams will use that version of the feature until the next merge (RI). When MAIN branches for release (current version), servicing of final ship-stopping bug fixes should be made in the RELEASE branch. The feature branch is just for next version work. In this example when MAIN branches for release all DEV branches can begin next version (vNext) work.
Next Version development As teams begin to wrap up their current version work items teams will want to begin next version work. Until a RELEASE branch is created from MAIN there is no appropriate place to check in next version work. Without guidance, individuals (certainly well meaning) will go through many unnatural acts to check in next version code and exclude it from the build. This sounds innocuous but will eventually cause problems ranging from broken builds to shipping next version code in your current release (having potential IP and legal implications depending commercial significance of your next version changes). The recommended solution is to create a development branch, under MAIN for next version work. You should only create this branch when needed since the presence of a next version branch will incrementally distract teams from shipping the current version of the product. Considerations for this branch are:
Branch all of the parent branch (usually Main) so the next version code builds along with the unchanged code.
25
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
Merge (FI) frequently (ideally once a day or when there are successful builds from the parent branch) to make sure the next version changes remain compatible with the latest changes from the peer development teams. Increment the build number (ideally major or minor) to indicate that builds from this branch are for the next version (vNext). Make sure all next version tools and test code are checked into this branch as well. DO NOT merge (RI) this branch to MAIN until after MAIN has branched for release. A merge (RI) from the next version branch to MAIN indicates all teams will begin next version work and any ship stopping fixes for the current version product will be made in the appropriate release branch.
Scratch or temporary branches Before creating a new branch for an individual to play in, prototype, or test changes in - it may be helpful to ask the following questions to see if there is a better alternative to creating a new branch. Using the options below may expose another area where the developer should be working, will prevent low quality, orphaned, or inappropriate code from getting into your source tree.
1. Can you use a shelveset? Frequently developers just want a way to save or share changes. A shelveset accomplishes both of these tasks by saving the changes in the TFS database but not committing them to the branch. 2. 3. 4. Is there another work item you should be working on? Sometimes other work is not visible to the individual engineer. Work in the next version branch mentioned above if the change is approved for next version release. If the work is truly not related to the project and for developer training use TFS 2010 basic edition to create a stand along TFS instance right on the developer desktop. This is completely separate from the production TFS that the team may be using. Consider using this for projects the developer would consider throw away (i.e. training) code.
The goal here is to keep the bar fairly high for creating a branch to keep the team focused on contributions that will help the current product ship or get an early start on the next version of the product. Every extraneous check in has an operational cost (i.e. storage, back up time, restore time, performance, etc.) so should be avoided.
RELEASE Branches
There will be hotfixes! anonymous Your release branch plan should be built around your software release vehicles. A release vehicle is how your software is delivered to your customer. The most common release vehicles are the major release, Hotfix and service pack. In a software plus services scenario the names may be different however and the release may be more frequent. The Advanced branch plan assumes that your software will require concurrent Hotfix, service pack and next version (MAIN). Almost all software servicing have a need for these classes of release so we setup 26
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers the release branch plan to support these from the very beginning. Note, that all 3 branches are created at the same time to ensure the correct parent child relationship.
After the release branches are created changes from MAIN should not merge (FI) into the release branches. Changes should merge one way from RELEASE to MAIN. Also, changes should always merge through intermediate branches (i.e. RELEASE -> HOTFIX -> SERVICEPACK -> MAIN) to ensure that bug fixes remain consistent in subsequent releases. Note, once you make your final change to your major release (i.e. the release branch in the diagram above) this branch should be set to read only. This branch is retained for compliance purposes only. Since there is no change history in TFS for labels the only sure way to know the state of your sources is to branch and ship your product from that branch.
27
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
Integrations
when ambition meets faith. anonymous The primary cost of a branch is in the time and potential for mistakes to be made during integrations. There is one solution to resolve this. The general guidance is below.
Keep branching to a minimum. Merge (FI) from parent to child frequently. Ideally do not let a branch get more than 1-2 days out of sync with the parent. Merge (RI) frequently from child to parent based on build and automated test results.
Build Quality
It works on my machine. anonymous A successful build only indicates that sources are syntactically correct and generated no build-time (i.e. compile, link, or packaging) errors. Before committing more resources, usually people, hardware and time, to testing this build its important to determine if this build is testable. This is the role of the Build Verification Test (BVT). BVTs should meet the following 3 requirements.
1. 2. 3. Fully automated 100% reproducible Failure of a BVT blocks more than 30% of your test organization.
The only 2 outcomes from a BVT failure should be a code change to fix the break or a test change to fix a broken test. If a BVT is frequently generating failures that are ignored then the BVT should be removed. Sample BVTs for an operating system would include, setup, joining a domain and writing a file to disk. Remember, these are very basic tests to indicate if the build is testable. More extended testing can be done outside of the build system.
These two new permissions allow teams to designate certain individuals to be responsible creating new branches, while others can be responsible for merging code between branches, while most developers will be restricted to working only on certain branches.
28
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers Manage Branch Permission Users require Manage Branch permission on a given path in order to: Convert folders to branches Convert branches back to folders Update metadata for a branch, such as owner, description, etc. Create new child branches from a given parent branch Change the relationships between branches with merge relationships (i.e. re-parenting branches)
Manage Branch permission only applies to branches (or folders that have been converted to branches). Users are not prevented from branching ordinary folders for which this permission has been denied. Manage Branch permission is scoped to a specific path. Branches can still be organized in folders. Thus Manage Branch permission enables a team to arrange their branches such that some branches can be further branched by users but other cannot. For example, if a team could deny Contributors Manage Branch permission for all branches organized under the paths: $/<TeamProject>/Main and $/<TeamProject>/Releases, but allow Contributors the Manage Branch permission for feature branches organized under the path $/<TeamProject>/Development. With these permissions, members of the TFS Contributors group can create child branches for development (from existing feature branches), but cannot create new branches from existing release branches or from the Main branch. Merge Permission Users require Merge permission in order to Pend merge operations on branches, folders, and files under a specified path. Merge permission is required for the target path of a merge operation. There is no permission to prevent a particular branch or folder from being merged to another path. Merge permission is not limited to branches it can be applied to folders and branches under a given path.
29
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article VSTS Rangers
Branch Re-parenting
TFS 2010 introduces the ability to change the parent-child relationships between branches.
Conclusion
No fate but what we make. anonymous We expect the branch plan presented here to work for most software development projects. If you have an unusual situation consider reviewing the scenarios companion package of this document to see if others have provided a solution to your situation. However, dont try to make your branch plan more complicated than what we have presented here unless you can justify the additional branches or unusual patterns.
30