Using Source Code Control in Team Foundation

Christopher Menegay
NotionSolutions

September 2005

Applies to:
   Microsoft Visual Studio 2005 Team System

Summary This article examines version control options available in Microsoft Visual Studio 2005 Team System. (17 printed pages)

**Note   **This document was developed prior to the product's release to manufacturing; as such, you may find inconsistencies with the details included here and those found in the shipping product. The information is based on the product at the time this document was created and should be used for planning purposes only. Information is subject to change at any time, without prior notice. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Contents

Introduction
Different Problems, Different Solutions
Controlling Documentation and Other Non-Source Code Artifacts
Basic Source Code Control
Enterprise Class Version Control
Working with Multiple Versions
Branching in Team Foundation Source Control
Merging in Team Foundation Version Control
Branching with New Iterations
A Paradox in Version Control
Shelving with Team Foundation Version Control
The Definition of Source Code
Tracking Tasks and Enforcing Standards
Conclusion

Introduction

Source code control is a common requirement in all modern software development projects. In its base form, it provides mechanisms for checking source code in and out of a central repository. This allows different developers to work on the same project, with reduced fears of lost code or overwritten changes. Source code control also implies a version control system that can manage files through the development lifecycle, keeping track of which changes were made, who made them, when they were made, and why. Finally, source control also frequently involves the ability to group versioned files as a single release, maintain multiple active releases concurrently (branching), and join different releases (merging).

This base form of source control is fine and can be useful for even single-developer project teams. However, these features become critical with larger enterprise applications with multiple release versions and teams of developers. Microsoft Visual Studio 2005 and Visual Studio Team System actually provide three distinct mechanisms for managing and tracking source code and other work products.

Different Problems, Different Solutions

Developers using Microsoft technologies have long been aware of Microsoft Visual SourceSafe. This product has been available for years, and has been readily available and bundled with Microsoft development tools. For small projects, it has been fair, providing small development teams with a cost-effective source control system. With some teams, developers would use Visual SourceSafe for their source code, and then create file shares to capture requirements documents, test cases, and other related work products. In other cases, the primary mechanism of source control would also be used to store and version the related work products. Enterprise developers and larger teams would frequently purchase expensive third-party source code and configuration management tools.

In evaluating options and learning from customer feedback, Microsoft has expanded their approach to source control and configuration management for Visual Studio Team System. The new release of Visual Studio will include three different mechanisms for controlling work products:

• Team Project workspaces and Microsoft Windows SharePoint Services
• Microsoft Visual SourceSafe 2005
• Team Foundation Version Control

Controlling Documentation and Other Non-Source Code Artifacts

Although the term version control typically refers to the ability to control developer source code, there are other work products that are typically built and managed during a software development project. These may be in the form of Microsoft Word documents containing the project vision, requirements, design, test plans, deployment procedures, and training plans. They may include Microsoft Visio diagrams to support infrastructure, architecture, and design. Even project plans and bug lists are typically managed as part of the development lifecycle.

Various project teams have found different ways to manage these artifacts. File shares are commonly used for this purpose. In this case, people typically use file naming conventions to track revisions of documents, or avoid versioning altogether.

Obviously, these options still exist, but there are currently better tools for managing project documentation. With the release of Microsoft Windows Server 2003 and Window SharePoint Services (WSS), all types of users receive easy access to version-controlled document libraries. This technology is available today, and it is licensed as part of Windows Server 2003. In addition to version-controlled documentation, a Web browser interface, and integration with Microsoft Office, development teams can also benefit from ancillary features of WSS, such as list management and discussion boards.

Visual Studio Team System builds upon the capabilities of WSS. A Team Project Web site is built automatically during creation of a new Team Project. This Project Portal is customizable as part of the Process Templates in Team System. By default, they expose document libraries for capturing and controlling artifacts of the development process. In addition, the workspaces provide appropriate document templates for the development process, a portal view, and reporting into the status of the project. Additionally, process guidance is available, to help lead users through the development lifecycle. The workspace is targeted not only at managers and business users through Microsoft Office and a Web browser, but also to developers and testers using Visual Studio.

Basic Source Code Control

Microsoft continues to acknowledge that Visual SourceSafe is suitable for small project teams with simple source code control requirements, and will release an updated version with Visual Studio 2005. This updated version will provide the same underlying file-system-based engine as the existing product. It is, however, significantly enhanced to make it a more viable option for small projects. Some of the enhancements include:

• Improved support for distributed teams, including accelerated WAN access and HTTP access, for remote users and regional time zones and languages.
• Improved stability and increased data storage to 4GB, with fewer requirements to analyze, administer, and repair databases.
• Improved support for custom and third-party viewers, merge tools, and editors.
• Improved automation capabilities, including custom .NET automation through the Primary Interop Assemblies for Visual SourceSafe, and integration capabilities with the new MSBuild build-management tool.
• Support for Unicode and XML, enhancing the ability to develop ASP.NET Web services and other project types that rely on Unicode.

Visual SourceSafe 2005 indeed has some compelling enhancements that may enable its use for small teams that have previously ignored it.

Enterprise Class Version Control

As a part of Visual Studio 2005 Team System and the new Team Foundation Server, Microsoft is providing a true enterprise-class source code control system. Team Foundation Version Control (TFVC) is provided as part of Team Foundation Server and offers integrated source control for Visual Studio 2005. Make no mistake about it: TFVC does not share any heritage with Visual SourceSafe. TFVC was written from the ground up to solve limitations of using VSS on large development projects. Instead of relying on a file system as the repository, TFVC leverages Microsoft SQL Server 2005 as a robust, scalable, high-performance storage mechanism.

Team Foundation Version Control provides all of the basic functionality of other source control mechanisms and most of the enhancements listed for Visual SourceSafe 2005. In addition, TFVC provides new advanced feature, including Shelving, checkin policies, and integration with the new work item tracking system. These features are described later in this article.

There are a few features that VSS users may miss from TFVC. These features include:

• Sharing—VSS provides a mechanism to make a file or folder in source control appear in multiple places in the source control structure. TFVC does not have an identical capability. Branching, however, can be used to simulate this behavior.
• Pinning—VSS provides a mechanism called "Pinning," which is used to pin a version of a file in such a way that it can't be modified. This is frequently used with sharing, to pin different versions of the same file in different share directories. As described below, the TFVC mechanisms for branching are more powerful, in that they allow different versions to be maintained independently.

Working with Multiple Versions

In addition to the standard capabilities of maintaining versions, locking, and history of individual files in a development project, modern source control systems support the ability to group versioned files. For example, if you release the first version of your project, individual files in the project may have already been modified numerous times. Hence, it's impossible to simply state that the initial release of a project is the same as the initial release of all the files in that project. Version control systems typically use "labeling" to allow you to define specific files and versions of those files as a group. Once the label has been applied, the files labeled together can be referenced as a whole later on in the development lifecycle. For example, labels can be created for nightly builds, allowing easy retrieval and reference of the file versions included in each build. Figure 1 depicts the labeling dialog box provided with Visual Studio 2005 Team System.

Figure 1. Labeling

Generally, development projects that make it to initial release will continue beyond that release. Unfortunately, maintaining multiple versions causes headaches for developers. For example, you may create the first version, V1.0, of your application and release it into production. What happens when you're in the middle of your enhancements for V2.0 and your users report a high priority bug that has to be fixed in the released version? You can try to merge your in-progress V2.0 code back into your V1.0 project. Sometimes this is successful, but as often as not, it will ripple into a nightmare of version incompatibilities and break as many things as it fixes.

Branching is the standard answer to this problem. When you release a version of your application, you create a branch of your files for the next version. Just like the branches in a tree, you can access all existing branches simultaneously. Now, when your high priority bug comes in on V1.0 of your application, you can go back to that branch and make the fixes, without worrying about the impact your V2.0 updates could cause.

The savvy developer will see a potential problem with branching—that is, now that you've prepared a new V1.1 release with the bugs fixed, how do you make sure that those updates are reflected in the V2.0 code that you're working on? Of course, manual differences and code updates is always an option. Another possibility is trying to make the updates on both versions simultaneously. The preferred solution, however, is the use of a merge tool from your source control provider.

Branching in Team Foundation Source Control

TFVC provides robust branching capabilities. Individual files, complete directories, or projects can be branched. Even complete Team Projects and solutions can be branched.

Although there are several ways to access the branching functionality from Visual Studio 2005 Team System, one simple way is to select the folder in the Source Control Explorer window, right-click, and click Branch in the shortcut menu. This will result in a dialog box similar to that shown in Figure 2.

Figure 2. Branching

Users can browse to or enter the destination location in the source control repository to store the new branch. Figure 3 shows the Source Control Explorer after a branch operation.

Figure 3. Branch results (click the image for a larger picture)

Merging in Team Foundation Version Control

Once the branching has occurred, the separate branches can be maintained independently, in such a way that changes in one branch don't affect the other. In many cases, at least some of the changes made in a maintenance release will be rolled forward into a new version. The TFVC Version Control Merge Wizard, shown in Figure 4, can be used to move the changes from one branch into another. To access the Version Control Merge Wizard, select the source folder in the Source Control Explorer window, right-click, and click Merge in the shortcut menu.

As the Wizard is displayed, users can select and verify the source and destination of the merge, and specify whether the merge will include all changes since the last merge, or only selected changes. You can also select specific changesets to work with, representing all files checked in by a single user at a single time, or accept all differences between the two branches.

Figure 4. Merge Wizard

During the merge process, TFVC will compare the differences in all of the selected files. When the files are different, the merge process will attempt to generate a current copy based on the the files in each branch. If the merge process is successful without user intervention, the merged files will be checked out and merged in the target. Note that TFVC can merge not only modified files, but also new files, deleted files, and even renamed files. If there are conflicts during the merge process that cannot be automatically resolved, the Version Control Change Wizard will request your assistance. You can choose to use either version of the file, however, as the final version, but in most cases, you'll probably choose to manually perform the merge. Manual merging displays the differences on a merge screen, with the file from the source branch on the left-hand side, and the file from the target on the right-hand side. You will have the ability to select the lines from each branch that you want in the final merged version. Figure 5 shows an example of the merge resolution screen.

Figure 5. Merge resolution (click the image for a larger picture)

Once the merge is complete, the resulting files will be represented as pending changes in your workspace, and you should test the merged version. Compile the projects and run your tests, to ensure that the merged version operates as expected, before checking it in to TFVC. If needed, additional files can be checked out to support the merge; TFVC handles changesets atomically, so all changes associated with the merge can be checked in as a single unit.

Branching with New Iterations

Visual Studio Team System provides customizable process guidance out-of-the-box. When creating a new Team Project, the project leadership selects which development process template is appropriate to their needs. For example, a project for building a flight control system for an airplane may have more rigid process requirements than a project for building a new version of Solitaire. The Visual Studio 2005 Team System product team understood that even between versions or iterations, project processes may change. This may be due to the evolution of your own processes, or to the acknowledgement that you require a different process for the second generation of your product than for the first.

Visual Studio 2005 Team System allows the selection of a starting point for your new Team Project, based on an existing project. As shown in Figure 6, you can not only create a new version control folder as part of the new project, but you can also create a branch from an existing project.

Figure 6. Branching a new Team Project

A Paradox in Version Control

Sometimes in the development process, we end up with a paradox. For instance, a common goal in development teams is to have the most current version software checked in to the source control repository at the end of every day. The central repositories are typically backed up with greater frequency than developer workstations, and other developers may need access to the most recent code as well. The problem comes in when we also say that we don't want any code in the source control repository that will break the build or otherwise disrupt the development process. Since some complex changes will take more than a single day to perform, it can be impossible to both have code checked in daily, and also not cause difficulties for other members of the development team.

TFVC fixes this situation by introducing shelving. By using shelving, users can store intermediate versions of their files in the source control repository, on a shelf. That is, the files are on the Team Foundation Server, accessible by other users, and backed up as part of your standard backup procedures. At the same time, this shelveset is NOT part of the version-controlled application source code; you will not be blamed for breaking the build because you checked in incomplete or otherwise misaligned code. To emphasize, the changes are uploaded and stored on the server, but they are not checked in.

Shelving can be helpful for any interrupted workflow, such as when you are called back from your current V2.0 updates to work on V1.0 bugs, or even if you decide to take a vacation and need to leave your current source code tasks as-is but available to your peers. In fact, shelving is also useful for general sharing between team members. Not only can other team members access your code shelf for interrupted workflow, but also for planned activities such as code reviews and buddy tests.

Shelving with Team Foundation Version Control

Shelving can easily be performed from within Visual Studio 2005 Team System. If you are working on files that have been checked out, you can place your updates in a shelveset from various places. Right-clicking in the Solution Explorer or Source Control Explorer will provide a Shelve command in a shortcut menu; shelving and unshelving are also available through toolbar buttons on the Pending Checkin window. As shown in Figure 7, clicking the Shelve menu command provides a dialog box, allowing you to select the items to shelve, as well as providing the shelveset name and comments.

Figure 7. Shelving (click the image for a larger picture)

Retrieving changes from a shelveset is as easy as putting them there in the first place. Clicking the File menu, Source control, and then Unshelve provides a dialog box similar to the one shown in Figure 8. This menu option is also available from shortcut menus in Solution Explorer. Note that, permissions allowing, you can pull changes from shelvesets created by others almost as easily as from your own shelvesets. Simply enter the other user's name in the dialog box and click the Find button. When you actually perform the unshelving, the changes in the shelveset will be pulled into your local project so that you can continue working on them.

Figure 8. Unshelving

The Definition of Source Code

As a version control system, it seems obvious that source code should be stored and managed in TFVC. Unfortunately, the definition of source code is somewhat less clear. For Visual Studio 2005 Team System, you can expect that anything that can be placed in a Visual Studio solution should be stored in TFVC. This obviously includes your .NET source code (for example, C# and Visual Basic) and ASP.NET files. It can also cover many other types of files. Direct supporting files such as data files, configuration files, and resource files should also be captured. Diagrams, including logical data center diagrams, application diagrams, and class diagrams, can't be left behind. And, of course, don't forget the database projects and your stored procedure code.

Make sure that your tests are captured and controlled in TFVC along with the source code they support. This includes all types of tests that are supported in Visual Studio 2005 Team System: Unit Tests, Web Tests, Generic Tests, Load Tests, and Manual Tests.

There are two important things to realize about storing tests in TFVC. First, testers are not second-class citizens; they will require access to source control in the same manner as developers. Second, manual tests must be stored and version-controlled just as any other source code artifact. This may be counter-intuitive, because manual tests are typically represented as text or Microsoft Word documents. It is not the format of the file as much as the purpose that it important. Whereas the Team Project workspace provides a collaborative environment for the business users and managers to gather requirements and track progress, the Team Foundation Server source code repository provides a place for those who actually create and verify a quality software system.

Tracking Tasks and Enforcing Standards

One of the great new features in Visual Studio is the ability to track different types of tasks between all members of a development team. From a user perspective, this means integrated access to assigned development or test tasks, bug fixes, risk management, requirements gathering, or any other work item appropriate to your development process. A hidden value that the work item system provides is a streamlined way to track work on requirements through design to development and test. In fact, by associating source code and test files to the work items, the tracking can go all the way from the vision and requirements to the final products of the work. There are many benefits to Work Item Tracking (WIT), including automated reporting and notifications. The details of the Work Item Tracking system are beyond the scope of this paper. However, realize that to enable this end-to-end traceability, users must perform the association of the files being checked in to source control with work items. Luckily, this is easily achievable using the work item channel in the Checkin dialog box.

The requirement to associate work items with development tasks is just one of many standards that may be desired in the development process. Several policies are included with Team Foundation Version Control that may be helpful in your development process, including:

• Work item association—Requires that anything checked in to source control be associated with a defined task within the work item system.
• Static code analysis—Requires that all code checked in to the source control system first be tested with the static code analysis tool (formerly FxCop). The static code analysis tool ensures that the source code meets coding standards.
• Unit testing—Verifies that unit tests exist, have been executed, and perhaps meet some minimal level of success.

Team Foundation Version Control supports the standards enforcement by integrating with the Checkin Policy capabilities provided in Visual Studio Team System. As of Beta 2, Visual Studio Team System supports four checkin policies out-of-the-box. These include Code Analysis, Testing Policy, and Work Items; Figure 9 shows the source control and policy settings from Visual Studio.

Figure 9. Adding a checkin policy (click the image for a larger picture)

In addition to the standard policies, developers can create custom checkin policies to support their development environment. By implementing the IPolicyDefinition and IPolicyEvaluation interfaces provided, custom policies can evaluate the checkin request, verify your requirements, and inform the Team Foundation Server as to whether the checkin will be allowed. And, of course, if the checkin is disallowed, the same components can provide feedback to the users so that they can remedy the problem and try again.

In addition to customization through policies, you can also customize Visual Studio 2005 Team System to require or simply allow checkin notes as part of the checkin process. Figure 10 shows the comments allowed with file checkin as defined in the MSF for Agile Software Development process templates. You can customize these comments using the Add and Remove buttons and the Required check boxes in the dialog box. You can also customize these checkin notes in your own custom process by modifying the Version Control Tasks XML file in the process templates.

Figure 10. Checkin notes

The checkin polices and notes provide a level of control that most organizations do not have today. Keep in mind that implementation of these policies is entirely optional. The checkin policies can, and perhaps should, be set as part of a process template that allows an organization to build the source control rules into the processes they use to run their projects. This creates a high level of consistency across development projects.

Conclusion

Obviously, Team Foundation Version Control has significantly more support than Visual SourceSafe for enterprise development teams. TFVC has many features to help manage artifacts. Features such as shelvesets, work item integration, checkin policies, branching, and merging add tremendous value to the management of project assets.

© Microsoft Corporation. All rights reserved.