Monday, September 07, 2009

Branching and Merging using TFS

The concept of branching and merging is simple but the mechanics of using TFS for branching and merging need to be understood carefully because it is prone to errors when users misses a step. Quick advice, practice branching and merging a few times with test projects before using it on your real project.

This section will outline a step by step walkthrough of the Branch-Merge process using TFS. But before the walkthrough, please go through the pre-requisites here and be thoroughly familiar before moving on.

Pre-requisites:
1. Read the official documentataion (this is not enough, but still need to be familiar with) at:
MSDN Library - Development Tools and Languages - Visual Studio Team System - Team Foundation - Team Foundation Project Members -
Working with Team Foundation Source Control - Branching and Merging Team Foundation Source Control.

2. Be familiar with Solution Explorer in Visual Studio (VS) - if not shown then access from View menu. Understand that Solution Explorer shows the LOCAL version of your code.

3. Know how to check-out and check-in projects between Local workspace and TFS server. This is another big area which you need to fully understand.

4. Be familiar with Source Control Explorer. This is a client to view your files that are stored in the TFS server. This is a server view of files on the server - they are not your local files.

5. Change Source Control. This is a crucial tool to check that your projects are in sync between LOCAL versions and TFS server versions. Access this by highlighting a project in Solution Explorer, then go to File - Source Control - Change Source Control.
Note that if the project is not in source control, then the link above will be: File - Source Control - Workspaces.

6. There is an existing project (create one if needed) called Test_BranchMerge in a Solution of your choice. This Solution and its project should be in your local PC and in the TFS server and is properly checked-in and the source control path properly synchronized (can be checked using Change Source Control - see step 5 above). In this project, there should be at least one source file, eg Source1.f90. This example project is a Fortran project, but it should apply to other projects recognized by VS.


Walkthrough of Branching and Merging:
1. Go to Solution Explorer and click on the Test_BranchMerge project. Check the following: i) On the Pending Change column, there is nothing pending. ii) in the Latest column, everything is Yes. iii) In the Local Path above, the path is pointing to the correct local folder.

2. BRANCH - In the Solution Explorer, right click on Test_BranchMerge project; select Branch. In the Branch dialog:
i) in the Target field, you change the last part of the name, but do not alter the other parts of the path. Example:
Target: $/aaa/bbb/ccc/ddd/Test_BranchMerge-branch
this can be changed to
Target: $/aaa/bbb/ccc/ddd/Test_BranchMerge-06
but do not change the server structure $/aaa/bbb/ccc/ddd
ii) Branch from Version: select Latest Version.
iii) Check the box "Create local working copies for the new branch.
iv) Click OK.
This process will create a branch in the TFS server as well as a copy of the project in your local directory under the same solution as the original project source.

3. VERIFY -
i) In Windows File Explorer (not in VS), the folder Test_BranchMerge-06 exist on the same level as Test_BranchMerge. All contents between these two folders should be identical.
For Advanced Users: the project files *.cproj (for C#), *.vfproj (for Fortran) which identifies the projects to VS are identical between Test_BranchMerge-06 and Test_BranchMerge. This means all systems including VS (except for TFS) will REGARD these two projects as IDENTICAL. In VS, Test_BranchMerge-06 will be recognized as Test_BranchMerge. This is the correct feature and effect we need for branching. See step 4 in using this new branch to work with.
ii) In the VS - Source Control Explorer, Test_BranchMerge-06 is visible on the Directory Tree on the same level as Test_BranchMerge, with a branching symbol next to it. Click on Test_BranchMerge-06 on the left pane and on the right pane, all the contents Test_BranchMerge-06 are visible. All contents have the branching symbol next to it. In the Pending Change column, all contents have state - branch.
iii) In the Solution Explorer, check that the Test_BranchMerge project is still visible. Note that this shows the local Solution which is still linked to the local source of the original Test_BranchMerge project. This will be re-connected manually in step 4. Click to highlight Test_BranchMerge project in Solution Explorer, then go to File - Source Control - Change Source Control. View that the Test_BranchMerge project has Server Binding pointing to $/aaa/bbb/ccc/ddd/Test_BranchMerge. Do not change anything. Click OK.
iv) Again highlight Test_BranchMerge in Solution Explorer, then look at the Properties Window (if not show, go to View menu).
Verify that the project path is still pointing to Test_BranchMerge folder in your local PC.

4. INITIAL CHECK-IN
This step is necessary if we want to work on the changes in the branched code. At the end of Step 2, although the branched project and source has been created in TFS and the local PC, it HAS NOT BEEN REGISTERED UNDER TFS.
i)In the Source Control Explorer, in the left pane, right click on Test_BranchMerge-06 and select: Checkin Pending changes.
ii) Verify - Look in the right pane, under the Pending Changes column and check that all the files under Test_BranchMerge-06 has NO pending status at all; ie. the branching symbols and branch pending status are gone.
At this stage, the new branch for the project has been cloned.


5. RE-CONNECT VS Solution to point to the new Branch.
At this stage, VS Solution is still connected to Test_BranchMerge folder locally.
i) Go to Solution Explorer, right click on Test_BranchMerge and select Remove.
ii) In the Solution Explorer, right click on the Solution (at the top) and select Add - Existing Project.
iii) In the dialog box that appears, navigate to Test_BranchMerge-06 folder on your local PC and select Test_BranchMerge.vfproj or Test_BranchMerge.csproj, etc... and click Open. Note that the project file is STILL named Test_BranchMerge.xxxx, not Test_BranchMerge-06.xxxx.

6. VERIFY - that the new branch is connected.
i) From the Solution Explorer, highlight the project Test_BranchMerge. In the Properties Window, check that the Project Path is pointing to the local folder Test_BranchMerge-06.
ii) From the Solution Explorer, highlight the project Test_BranchMerge. Go to File - Source Control - Change Source Control. Looking at the project Test_BranchMerge - check that its Server Binding is set to $/aaa/bbb/ccc/ddd/Test_BranchMerge-06. Check that the Connected box is ticked and the Status is Valid.
This shows that for all intent and purposes, the branch is now recognized as the Test_BranchMerge project (not Test_BranchMerge-06). The paths to the server and local PC shows that the project is linked to the correct branch folder Test_BranchMerge-06.

7. WORK IN THE BRANCH
In the VS environment, modify the code, run the program, do whatever as normal. The Test_BranchMerge project should work as usual before branching. Even the Check-in proces to TFS should work as normal. As noted before, the source code is now connected to the branched version Test_BranchMerge-06, both locally and on TFS.
i). In the Solution Explorer, in the Test_BranchMerge project, open up the file Source1.f90. Edit this file, save it.
ii). Note the TFS locked symbol next to Source1.f90 changed to the red tick symbol indicating that the code is updated and different to the TFS version.
iii). If the red-tick edit symbol does not appear, then in Solution Explorer, click on Source1.f90, select Check-out for Edit. Then edit the code and save.
iv). Once all code changes are done, click on the Test_BranchMerge project in Solution Explorer and select Check In.

8. MERGE - like branching, merging must be done via Source Control Explorer. Branch - Merge are TFS operations, they are not VS operations.
i) From the Source Control Explorer, right click on the Test_BranchMerge-06 project, and select Merge.
ii) In the Merge dialog, choose the following:
Source Branch: $/aaa/bbb/ccc/ddd/Test_BranchMerge-06
Select: All changes up to a specific version
Target Branch: $/aaa/bbb/ccc/ddd/Test_BranchMerge
iii) Click Next, choose Latest Version as the Version Type, click Next, click Finish.
Note the merging occurs between code in TFS server, not your local version. Hence before merging, both old and new branch must be fully checked in. Also note merging occurs from Branched version as Source to Target original version.
iv) Verify - in the Source Control Explorer, click to highlight the original project Test_BranchMerge. Looking at the right pane under the Pending Change column, note that the files which has been changed will now have the "merge, edit" status.
v) Checkin - in the Source Control Explorer, right click Test_BranchMerge and select Checkin Pending Changes.
vi) Verify - if checkin is successful, then the files with "Merge, Edit" Pending Changes (step iv) above) will now have NO pending change status.

9. CONTINUING WORK
In VS, remember that the Test_BranchMerge project is still linked to the branched version Test_BranchMerge-06 code base. The user now has many options such as:
i) Continue working with the Test_BranchMerge-06 branch. The user can keep on editing code in VS under the Test_BranchMerge project, with no extra re-configuration.
ii) Revert back to work with original branch (which now has the merged changes). In the Solution Explorer, remove the Test_BranchMerge project (which is actually the Test_BranchMerge-06 branch). Then click on Solution in the Solution Explorer and Add Existing Project; select the xxxx.xxproj file from Test_BranchMerge folder.
iii) Work from a totally new branch, eg using a new branch Test_BranchMerge-07. To do this, repeat the whole process from Step 1.



There may be variations of how the branch-merge process can be done; the walk-through shown above is just one scenario that should just work without having to spend more time investigating an error prone process.

No comments: