BA 372 - Source Control Lab

In this lab we'll learn about handling source code using the source control tool that is part of the Team Foundation Server component of Visual Studio 2008 Team System. Source control is a mechanism by which the source files that contain the code for a project are managed as they change over time. It provides a way to track who changed the code, when and what they changed, and other file management tools.

Each of the following subsections deals with the various operations one can do using Visual Studio's source control component. We will go over the steps for opening a project / solution managed by TFS, getting the latest version / specific version of the code from the source control, checking in changes made to the source, shelving and un-shelving changes made to the source, comparing any two versions of source and resolving conflicts which can occur as part of checking in or checking out the source code.

Connecting to Source Control  (Team Foundation Server)

1. First, lets ensure that team foundation server is in fact installed on the machine you want to be using. The client for TFS is integrated into Visual Studio 2008, so open that first (it should be on the start menu). Click on the Tools menu item; if it is installed you will see the menu item Tools>Connect to Team Foundation Server (See Fg. 1.1). If you do not have this option stop now and contact your teacher or the helpdesk for assistance.
2. Connect to the Team Foundation Server by navigating to Tools>Connect to Team Foundation Server...
   (See Fg. 1.1). The first time you use TFS (and every time you first use it on a new machine) it will need to have some basic information entered to determine where the Team Foundation Server is located. TFS operates like Exchange Server in this regard, all settings and data are server-side. In the "Connect to Team Foundation Server" window (See Fg. 1.2) click on the dropdown to see if you are already connected to "cob-tfs08". If yes proceed to step 4. If not, click on "Servers" to be able to add a connection.
3. This opens the "Add/Remove Team Foundation Server" window. This dialog has an 'Add' option, click on that. This will take you to the "Add Team Foundation Server" window. In the "Team Foundation Server name" field enter "cob-tfs08" and ensure the port number is 8080 and the protocol is "HTTP" (See Fg. 1.3). Click on OK. This will add the server to your list of servers which will show up as in Fg. 1.4. Now click on Close. 
4. You should now select "cob-tfs08" as the team foundation server in the drop down (See Fg. 1.5). You'll now need to select the team project you want to be able to have access to. Check the "Sp09_BA372_Lab" project. (See Fg. 1.6).
5. This team project is now listed in your Team Explorer Window (See Fg. 1.7). If you expand the team project there are several options including Source Control. The documentation and reports options may not be available with a red X next to them. This is normal. The Work Items node is a place to store and manage various work tasks, requirements, bugs, etc. for project management purposes. The documentation node is a list of document libraries from a corresponding SharePoint portal for the team project. The Reports node is a SQL Server Reporting Services site where reports about work items are stored. The Team Builds node is a place to store configured builds which can be automated to run to build the application for testing or release. The Source Control node is what this lab will focus on and is where the source code is managed.

1.1 - TFS Navigation

1.2 - Connect to TFS

1.3 - Add Server

1.4 - Server added

1.5 - Select Server

1.6 - Select Project

1.7 - Team Explorer

Opening Solution from Source Control Explorer

1. In the Team Explorer window, there will be a menu item called "Source Control". This will open the "Source Control Explorer" when you double click on it (See Fg.2.1 ).
2. In the Source Control Explorer window drill down to a folder having the same name as your ONID login name. Under that, select the solution folder BA372_TFS. Clicking on that will show you the contents in that folder in the adjacent window pane.
3. Since you are opening the solution for the first time, you'll notice that there is a "Not Mapped" value next to the "Local Path" field (See Fg. 2.2). This means, this solution hasn't been "mapped" into a directory local to the current machine you are on, as yet. A source control repository stores all the files on the server in a database. Therefore, if you wish to change a file you must first copy down a version to your machine. This is known as a source control "Update" or "Get". You'll have to follow this mapping procedure every time you open a solution for the first time on a machine. All subsequent "Get" actions will overwrite / update the copy mapped on to your work space.
4. To map and open the solution, double-click on the solution file (BA372_TFS.sln). In the "Browse For Folder" window choose an appropriate location for your solution (Select C:\ and click on "Make new folder". Name it as BA372_TFS_yourname, for example BA372_TFS_maiyam). Click on OK (See Fg. 2.3). You'll see the files being copied and the solution will show up in your Solution Explorer window for you to browse and edit (See Fg. 2.4).

2.1 - Source Control

2.2 - Not Mapped

2.3 - Mapping Source

2.4 - Solution Explorer

Checking in Pending changes

1. Changes made to the checked out code can all be committed to the Project repository by following these steps.
2. Add a comment "Line 6: This change will not be checked in" in the "Module1.vb" file (see Fg. 3.1).
3. Now change the comment on line 4 of Readsql.vb to "Line 4: Comment added during first check in"(see Fg. 3.2).
4. Notice that these two files now have red check marks next to them in the Solution Explorer showing that you now have them checked-out. Depending on your settings you may have been prompted to check the file out when you first began changing the file. This "check-out" is recorded by the server such that it is possible to know who is making changes to which files currently across the entire network.
5. Now navigate to the "Pending Changes" window ( View>Other Windows>Pending Changes) (see Fg. 3.3).
6. You will see a list of files having changes (all check marked) that need to be committed. You can choose to check in changes made to only a subset of these files by un-checking the ones you don't want to check in. Uncheck Module1.vb (see Fg. 3.4).
7. Now, add the comment "First Check In" in the text area "Comment:", just above the file list (see previous figure).
8. Click on the "Check in" button. You should see files being committed to the repository.
9. The version on the repository has the comment you just added to the Readsql.vb file.

3.1 - Modification 1

3.2 - Modification 2

3.3 - Pending Changes

3.4 - Check in

Undoing changes to source code

1. There are times when you have made changes to a set of files you checked out, but would like to revert all or few of the files to their original state (version on the source control server). In other words, you may want to be able to undo all changes you made to some or all the files, at once. Here's a really simple way to do that.
2. Let's undo changes done to the Module1.vb file. Navigate to the Pending changes window and right-click on the Module1.vb.
3. Click "Undo" (See Fg. 4.1). An "Undo Pending Changes" sub window pops up. Here you can select any other files you want to undo. In our case it is just this one file.
4. After making sure that the Module1.vb is checked, click on "Undo Changes" (See Fg.4.2)
5. Click "Yes" in the "Confirm Undo Changes" dialog (See Fg. 4.3).
6. You'll see that Module1.vb file no longer has the red check mark next to it in the Solution Explorer Window. This indicates that
   the version of the files you have in your local copy is the same as that on the repository and that you no longer have the file checked out. Open Module1.vb file. You'll see that the comment you added is indeed gone. This confirms your undo action succeeded. (See Fg. 4.4).

4.1 - Undo-navigation

4.2 - Undo Changes

4.3 - Undo Confirm

4.4 - Soultion Explorer

Shelving / Un-shelving changes

1. You can save a copy of all (/part of) the changes you made to files you checked out in the repository itself, without having to check-in those changes. This is typically done in scenarios where you don't want to lose your updates to a set of files but the task you want to achieve is still a "Work in Progress" and so you cant really commit your changes as yet. You can place your updates in a shelve-set, and un-shelve them whenever you are ready to continue working. This is also useful in scenarios where you want to share your changes with other team members for review without committing them. Here's how you shelve and un-shelve your changes.
2. Change the comment you added to Readsql.vb earlier to " Line 4: Changed comment for Shelving" (See Fg. 5.1).
3. Right click on the Readsql.vb file in the Solution Explorer and click on the "Shelve Pending Changes..." option (SeeFg. 5.2).
4. Here you can select all the files you want to shelve. In our case you'll see only the Readsql.vb file listed. Ensure it is checked.
5. Enter "BA372TFS_Shelve_Exercise" as the "Shelveset name".
6. Enter the comment "First shelveset" in the comment field.
7. Un-check the option at the bottom that says "Preserve pending changes locally". This will "undo" our changes locally after saving those changes to the shelf and remove our "check-out" on the file.
8. Click on "Shelve" (See Fg. 5.3). This will shelve your changes and undo the local copy. If you look at Readsql.vb you will notice the last change you made is no longer there on this local copy.
9. Let's see how un-shelving works. Ensure Line 4 on Readsql.vb shows "'Line 4: Comment added during first check in".
10. Right click on the Readsql.vb file in the Solution Explorer and click on the "Unshelve Pending Changes..." option to navigate to the Unshelve window.
11. In the Unshelve window (see Fg. 5.4) select the shelveset "BA372TFS_Shelve_Exercise" (You can also search by
    the comment "First Shelveset" you entered).
12. Click on Details. This will Open "The Shelveset Details" window where you can further select or deselect specific files you want to unshelve. Ensure you check the "Preserve shelveset on server" option if you want to retain the shelveset for future reference (See Fg. 5.5).
13. Click Unshelve and click Yes on the dialog box that asks if you want to reload the changed file(s). You'll now see that your copy of the source has been updated with the changes from the shelveset. If you open Readsql file you'll see that line 4 now reads "'Line 4: Changed comment for Shelving".

5.1 - Modification

5.2 - Shelve Navigation

5.3 - Shelve Dialog

5.4 - Find shelvesets

5.5 - Unshelve

Checking out specific version of code

1. For this exercise we will need at least two different versions of the files on the repository. So go ahead and check in your source now. Refer to section "Checking in Pending changes" if you are not sure of how to do this.
2. Now change Line 4 of Readsql.vb to "'Line 4: Comment added- Check in 3". Save your changes and check your changes in with the comment "The third check in".
3. To get a specific version of the source file, right click in the Solution Explorer window on the Project file at the root and select "Get Specific version.." (See Fg. 6.1).
   
4. You can further select the specific files you want in the "Get" window. Let's get all the project items, so ensure everything is checked. You can choose the version based on a Changeset, Date, Label, Workspace Version or simply get the "latest version" by making the appropriate selection in the "Type" drop down. Let's get a version based on the Changeset (changeset is a set of changes that are committed during a 'check-in' operation). Once you select "Changeset" in the Type drop down you'll see a browsable "Changeset:" field (See Fg. 6.2). Click on the browse button.
5. In the "Find Changesets" window, navigate to the BA372_TFS folder in $/Sp09_BA372_Lab/user/BA372_TFS/BA372_TFS
   in the "Containing file:" field. Then click on the "Find" button. You should see a list of changesets (See Fg. 6.3).
6. Let's retrieve the very first version we checked in. Select the changeset with the comment "First Check In" and click OK (See Fg. 6.4). In the "Get" Window you'll notice that the selected changeset number appears in the "Changeset:" field. 
7. Now select both the "Overwrite writable files..." and the "Overwrite all files..." options (See Fg. 6.5).
8. Fianlly, click on the "Get" button. This completes getting a specific version of the Source files from the repository.
9. To verify this, open Readsql.vb and observe Line 4. You'll see that the comment now reflects the first change you made and checked in! You should see "'Line 4: Comment added during first check in" if you successfully retrieved the specific version.

6.1 - Get-navigation

6.2 - Get Specific

6.3 - List of Changesets

6.4 - Select Changeset

6.5 - Ready to get

Comparing two versions of code

1. You can compare the version of source file(s) you are working on, with a version indexed by Changeset, specific date, specific Label or simply the latest version on the repository. You can do this by doing a right click on the file you want to compare versions of, in the Solution Explorer and clicking on Compare. In our case do a right click on Readsql.vb and click on "Compare" (See Fg.7.1)
2. In the Compare Window you'll notice that the Source path field points to the checked out copy of the file. You can configure this to point to a location on the server. This way you can compare two versions on the server. The Target path field points to the latest version on the server by default. You can configure it to point to a copy on your local machine, if you want to compare two local versions of the file.
3. For this exercise set the Compare window to compare the current local copy of the file with the latest version on the repository (see Fg. 7.2). This is the set on the window by default, which means you don't have to make any changes. Click on Ok
4. This opens a window where all differences between the sources from the two versions are displayed. You'll see that the section on the left half of the window displays latest source on the server and the section on the right displays source on your local copy. You'll also see that depending on your changes Deleted Text, Changed Text and Inserted Text will be highlighted with red, blue and green colors respectively. You can sift through all the differences by clicking on the "Next Difference" button, if there are more than one difference.In our case, we overwrote the latest(third check in) version we had with the First check in version in the previous section. So accordingly, you'll see that the only difference is in line four of the file, where the latest version has " 'Line 4: Comment added- Check in 3" as a comment while the local copy has a "'Line 4: Comment added during first check in" as the comment!! (See Fg. 7.3)
5. Close the Compare window once you are done going through the differences.

7.1-Compare-Navigation

7.2 - Compare Window

7.3 - Diff Window

Resolving Merge conflicts

1. When multiple people access the same code base we may encounter situations where two or more people access the same file and make conflicting changes to it. If this happens the first person to check in his code will have no issues doing so. However, when the second person tries to commit his changes the source control complains about there being conflicting changes to the file and one of the different ways of merging these changes needs to be done before the check-in can go through. This is just one example where a merge conflict can occur. We will create a scenario for one such conflict and see how one goes about resolving it.
2. Undo all pending changes on your source files. Make a minor change in Readsql.vb; Change Line 4 to "'Line 4: This change is to induce a Merge Conflict". Add another comment just below it. Add this on line five "'This comment will simply be merged without any conflict being flagged". Save your changes but don't check-in quite yet (See Fg. 8.1).
3. Now let's try and get the latest version from the repository. Remember the latest version is the final check-in we made when we  changed the comment to "'Line 4: Comment added - Check in 3". Let's see if this works.
4. Get the latest version (recursively) of the whole solution. Do a right click on the root; BA372_TFS in the Solution Explorer window and select "Get Latest Version (Recursive)" (See Fg. 8.2).
5. You'll see that the get does not go through and you get a "Resolve Conflicts" window (see Fg. 8.3). It provides a list of files (1 in our case) which need to be resolved. Some conflicts can be automatically merged by clicking "Auto Merge All". If the system fails to merge we will be redirected to the manual merge window. We'll directly do a manual merge in our case. Click on "Resolve".
6. This will lead you to the file specific version conflict window (See Fg. 8.4). You can see various Resolution options. Select the "Merge changes in merge tool" option and click on OK.
7. This is the actual merge window where you'll find the two conflicting versions of the file along with the editable merged output version of the file being displayed (see Fg. 8.5). For each of the changes you can choose either of the versions by clicking on the line(s) of code highlighted indicating they are changes. You can also edit the merged output file. You can go through each of the changes using the navigation buttons provided at the bottom (for an example resolution see Fg. 8.6). For this click on the change in the left pane and then click on the change in the right pane.
   
8. We now have all the three comments merged! After resolving all the conflicts you can click on OK.
9. You will be prompted to save the merged version of the file (See Fg. 8.7). Click on OK. Your local copy of the file is the merged version, but you haven't committed this change to the repository yet! These changes are only local at this point.
10. Now check-in the merged changes.
11. Your copy of Readsql.vb should now look like Fg. 8.8.

8.1 - Modifications

8.2 - Getting Latest

8.3 - Resolve conflicts

8.4 - Manual Merge

8.5 - Merge Window

8.6 - Example Merge

8.7 - Save Merge

8.8 - After Merge

Source control locks

1. When you check out a file for edit in Team Foundation Source Control you can optionally select one of the three lock types - None, Chek-out or Check-in.
2. Lock "None" : The file is not locked. a user may check out the file after you have, make changes and check those changes back in. At the point when you come to check in files you will be prompted to resolve any conflicts that could occur.
3. Lock "Check-out" : The file is locked on the server so that no user may check the file out after you have it checked out. This is useful if you are making changes to the file and you do not want anybody else to be able to start editing the file until you have released the lock by checking in the file or un-locking it. You cannot place a lock of "check-out" on a file if somebody already has checked out the file with any other lock type.
4. Lock "Check-in" : This lock prevents anyone else from committing their changes to that file until you have released the lock
   This means that they will be responsible for performing any conflict resolution activities that result. You can place a check-in lock on a file if somebody has a file checked out with a lock type of "none".