Date post: | 10-May-2015 |
Category: |
Business |
Upload: | timo-kuisma |
View: | 2,053 times |
Download: | 2 times |
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
1
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
2
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
3
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
4
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
5
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
6
Introduction Welcome to the Microsoft® Visual Studio® (VS) 2010 Team Foundation Server (TFS) Branching Guide!
Since the original release of this guidance in 2007 we’ve 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 real-
world 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
7
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).
Branch Plan – quick start “Save your creativity for your product… not the branch plan.” – anonymous
Below are four branch plans representing Basic, Standard, Advanced, and Mature software development
projects. The elements of these plans are additive; starting with the Basic plan will allow you to
transition to the Standard plan if your product or branching requirements become more complex.
The most common reason for adding complexity to a branch plan is the need for additional release
vehicles (i.e. Service Packs and Hotfixes). Additional release vehicles will require a branch plan that
supports concurrent development for each of these. Minimizing the number of release vehicles is one
key to keeping your branch plan simple.
The goal of the Basic, Standard, Advanced, and Mature branch plans presented below is to cover most
customer branching scenarios. Please post your scenarios not covered below to the community section
associated with this document at http://www.codeplex.com/TFSBranchingGuideII . Our hope is to
leverage the Codeplex community to cover alternative (but still valid) branch cases.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
8
Basic Branch Plan Below is a basic plan that enables concurrent development for your next release, a stable MAIN branch
for testing and a release branch for any ship blocking bug fixes.
Multiple development areas are supported by creating additional development branches from MAIN.
These are peers to each other and children of MAIN.
Additional releases are supported by creating additional release branches for each product release.
Each release branch is a child of MAIN and a peer to each other (e.g. release2.0 branch is peer to
release3.0 and both are children of MAIN).
Once the release branch is created MAIN and the development branches can start taking changes
approved for the next product release.
Figure 1. Basic Branch Plan
Figure 2. Basic Branch Plan - Branch Hierarchy Visualization
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
9
Figure 3. Basic Branch Plan - Folder and Branch Structure
Figure 4. Basic Branch Plan - Main Branch Relationships
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
10
Figure 5. Basic Branch Plan – Visualizing a Changeset – Hierarchy View
Figure 6. Basic Branch Plan - Visualizing a Changeset - Timeline View
The Basic branch plan will work well for your organization if you meet some of the following criteria:
1. You have a single major release that is shipped (i.e. a single release vehicle) to customers.
2. Your servicing model is to have customers upgrade to the next major release.
3. Any fixes shipped from the release branch will include all previous fixes from that branch.
Key elements of this plan include
1. DEVELOPMENT (DEV) branches for next version work.
a. Focus on wide, flat branches to enable steady code flow to MAIN and then back to peer
DEVELOPMENT branches
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
11
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.
d. DEVELOPMENT branches should build and run Build Verification Tests (BVTs) the same
way as MAIN.
e. Forward Integrate (Merge (FI) with each successful build of MAIN
f. Reverse Integrate (RI) based on some objective team criteria (e.g. internal quality gates,
end of sprint, etc.).
2. RELEASE branch where you ship your major release from.
a. RELEASE is a child branch of MAIN.
b. Your major product releases from the RELEASE branch and then RELEASE branch access
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.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
12
Standard Branch Plan As you add additional release vehicles you may need to create additional branches in the
production/release area to enable concurrent development. The Standard branch plan below
introduces a new release branch to support an additional release vehicle. Most organizations will call
this a servicing branch to enable development of Hotfixes and Service packs.
Figure 7. Standard Branch Plan
Figure 8. Standard Branch Plan - Branch Hierarchy Visualization
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
13
Figure 9. Standard Branch Plan - Folder and Branch structure
Figure 10. Standard Branch Plan – Visualizing a Changeset – Hierarchy View
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
14
Figure 11. Standard Branch Plan – Visualizing a Changeset – Hierarchy View
This plan will work well for your organization if you meet some of following criteria:
1. You have multiple ship vehicles (e.g. major release and additional service packs for that release).
2. You want to enable concurrent development of service pack and next version products.
3. 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. RELEASE tree (i.e. SP and RELEASE) are branched from MAIN at the same time to create
MAINSPRELEASE parent/child relationship.
2. Product releases from the RELEASE branch and then that branch is changed to read only.
3. Servicing changes are checked into the Service Pack (SP) branch.
4. Changes SP branches merge one-way to MAIN (SPMAIN).
5. Ship stopping bug fixes checked into the release branch should merge back to MAIN through the
SP branch (RELEASESPMAIN).
6. Duplicate RELEASE tree plan for subsequent major releases.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
15
Advanced Branch Plan The Advanced plan is for products have must support many release vehicles and servicing scenarios.
The plan allows for concurrent development of a major release, service packs, Hotfixes and next version
work.
Figure 12. Advanced Branch Plan
Figure 13. Advanced Branch Plan - Branch Hierarchy Visualization
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
16
Figure 14. Advanced Branch Plan - File and Branch structure
Figure 15. Advanced Branch Plan – Visualizing a Changeset – Hierarchy View
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
17
Figure 16. Advanced Branch Plan – Visualizing a Changeset – Timeline View
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. Changes in HOTFIX and SP branches merge one-way through intermediate branches to
MAIN (HOTFIXSPMAIN).
e. 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.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
18
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.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
19
Mature Branch Plan
Figure 17. Mature Branch Plan
Figure 18. Mature Branch Plan - Branch Hierarchy Visualization
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
20
Figure 19. Mature Branch Plan - Folder and Branch Structure
Figure 20. Mature Branch Plan - Visualizing a Changeset – Hierarchy View
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
21
Figure 21. Mature Branch Plan - Visualizing a Changeset – Timeline View
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
22
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.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
23
All I need is MAIN… Some teams are small enough that only one branch, MAIN, is needed. This is great but almost always
short-lived. Eventually individuals or teams will need some sort of isolation to work on next version
work, complicated bug fixes or breaking changes.
If you do not create a specific place for development work, developers will create their own. The danger
here is that the ad-hoc branch created by the developer may not have a natural branch path back to
MAIN.
Since these situations are inevitable it is best to have the development branch plan ready when needed.
If ever you need advice on when to branch, think of this:
Create a new branch when the check-in policy is so restrictive you can’t do work.
This means when the check in policy of your MAIN branch is to take version 1.0 changes only and you
have a version 1.1 changes then that would be a good signal to create a child branch of MAIN for your
1.1 work.
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 Be in sync with parent branch
o Build successfully
o Pass BVTs
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
24
Multiple Development Branches Earlier in this document we described the incremental cost of each branch. Nevertheless, there are
several scenarios where you should consider multiple development branches. The most common
scenarios are:
Breaking changes
A breaking change is a change to one component that will break another. A common example is when a
required parameter is added to a function in a shared library. Unless you coordinate the change to the
shared library and update all of the callers you will have broken builds until all affected components are
updated.
If everyone working on the project is within shouting distance a low tech solution is to announce your
change, ask everyone to check in their latest changes, submit your change to the updated library, then
update any callers to the updated library.
Once your team exceeds more than a few developers this low tech strategy will be too complex to
manage and frustrating for folks on the team. It will be especially upsetting for any stakeholders who
are wondering why check-ins are blocked. At this point branching is the best tool for the job.
Before creating your breaking change branch consider the following:
Branch from a parent with the latest changes (usually MAIN or another DEV branch).
Merge (FI) frequently, at least every day.
Build and run, at least BVTs from the breaking change branch.
Make your changes, build and pass all BVTs before merging (RI) the breaking change and
supporting changes to the parent.
Look for changes in the parent branch that where made between the last merge (FI) to your
breaking change branch and the merge (RI) (this should be a small window, less than a few hours)
to determine if these changes need to be updated.
o An example here would be a new component that was checked into the parent, not
included in your last merge to the breaking change branch. This caller would not have
been updated and may break a build or BVT.
After the breaking change has been merged (RI) the branch can be left idle (i.e. no merges or
check-ins) until needed for another breaking change. Another merge (FI) from the parent will
make this branch current again.
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.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
25
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.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
26
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. Is there another work item you should be working on? Sometimes other work is not visible to the
individual engineer.
3. Work in the “next version” branch mentioned above if the change is approved for next version
release.
4. 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
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
27
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.
Figure 22. Release Branches
A successful release branch strategy enables the following 3 scenarios.
1. Developers only need to check in once based on which release vehicle the change is for (i.e.
Hotfixes go into the product HOTFIX branch).
2. No need for baseless merges. Create a natural merge path back to MAIN by creating a hierarchal
branch structure based on your release vehicles.
3. Reduce risk of regressions. By creating a parent/child branch relationship between MAIN->SP->
and HOTFIX branches changes are naturally merged into future release (i.e. Hotfixes merge into
the SP branch on their way to MAIN) reducing risk of bug regressions in future releases.
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.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
28
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 it’s 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. Fully automated
2. 100% reproducible
3. 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.
TFS 2010 Branch and Merge Permissions TFS 2010 introduces two new permissions related to branching and merging:
Manage Branch
Merge
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.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
29
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.
Change History and Visualizing Changesets TFS 2010 introduces an improved View History feature. It is now possible to view change history across
branches. For example, when you right-click on a team project, you can view all changesets that were
checked into any branch within the Team Project. Similarly, when you view history for a specific file, you
can see change history associated with that file across all branches that file has been checked-into.
From the Change History view, you can select a single changeset and visualize changes for that
changeset. This view will show which branches contain a given changeset. The timeline view will show,
over time, how the changeset has been moved (as a result of branching and merging activity from one
branch to another.
VS 2010 TFS Branching Guidance Release 2010, 12/14/2009 Main article
VSTS Rangers
30
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, don’t try to make your branch plan more
complicated than what we have presented here unless you can justify the additional branches or
unusual patterns.