Migration from Legacy Version Control Systems - Version Control - Professional Team Foundation Server 2013 (2013)

Professional Team Foundation Server 2013 (2013)

Part II

Version Control

Chapter 9
Migration from Legacy Version Control Systems

What's in this chapter?

· Understanding the difference between upgrade and migration

· Comparing tip versus history migration techniques

· Migrating from Visual SourceSafe using the wizard

· Understanding Team Foundation Server Integration Platform

· Getting to know third-party tools for other legacy systems

Most teams adopting Team Foundation Server don't have the good fortune of starting from the very beginning with their applications. More than likely, there is an existing repository of source code that teams will want to move in some capacity into Team Foundation Server so they can continue software development from there.

That team may be using the latest version of Microsoft Visual SourceSafe (VSS) only to find themselves in an unsupported scenario since July 2012, which was when Microsoft discontinued mainstream support for Visual SourceSafe 2005. The team's goal may be to move to a new version control system, such as Team Foundation Server or Visual Studio Online, so that they can receive support if they are in a situation where they might need it in the future. They may also be using one of the other available version control systems—either commercial or open source.

One thing is certain: The process of moving to a new version control system gives you the rare opportunity to reorganize and clean up parts of the source code organization that has needed attention. This chapter explores the different options available for migrating existing source code into Team Foundation Server.

Migration Versus Upgrade

Team Foundation Server administrators may say that they want to migrate from a previous version of Team Foundation Server to Team Foundation Server 2013. More than likely, they mean that they want to upgrade to the newer version. If the Team Foundation Server administrator chooses the incorrect approach, the team will experience a loss of data and more work through the transition to Team Foundation Server 2013.


The term upgrade refers to the process of using the Team Foundation Server Upgrade configuration wizard to move data from a previous version of Team Foundation Server to the latest version. This scenario is different from setting up a new Team Foundation Server 2013 server and then attempting to “move” source code and work items into that new server. Upgrades are always fully supported and are tested in many configurations before being released. In an upgrade, data on the server is transformed at the database level, and all data and metadata are preserved.

By using the appropriate configuration wizard, the process is capable of using a full-fidelity upgrade to keep all of the data and history with the least amount of effort for the administrator and the team members using the server.

There are also different types of upgrades, such as the following:

· In-place upgrade—Defined as an upgrade that, when complete, will use the same set of hardware running the current Team Foundation Server version.

· Migration-based upgrade—Defined as an upgrade involving a second, duplicate set of hardware that will host the new version of Team Foundation Server when the process is complete. Note that, despite having a similar name, a migration-based upgrade isnot a migration.


Chapter 27 examines topics related to the process of upgrading Team Foundation Server from previous versions.


A migration refers to the process of replaying actions from one system into another system. One of the key differences, as compared to an upgrade, is that a migration is a lower fidelity data transfer. In Team Foundation Server, only version control and work item tracking data can be migrated between servers. Build data, reports, and numerous other pieces of metadata cannot be migrated. In general, available migration tools have significantly less testing than the upgrade process, and most available tools have limited support (because they are released out-of-band for the normal release).

In the case of a migration, the data transformations are done using only the public APIs, which are limited to providing only certain pieces of information while moving data. The result of these limitations is that some data is lost or distorted in the process of migration. Examples of this are artifact IDs (changeset numbers, work item IDs), date timestamps, area paths, and iteration paths.


Matthew Mitrik, a program manager on the Team Foundation Server Version Control team, has written several blog posts about this particular concept and discusses each of the different scenarios. For more information, visithttp://aka.ms/TfsUpgradeOrMigration.

Migrating History or Latest Version

One of the first determinations your team must make is whether you want to migrate all of the source code history from your legacy version control system or just take the latest version (which is sometimes referred to as the tip version) at a particular milestone. Most teams will immediately answer, “We want the history. We cannot move without all of the history.” However, that may not always be the wisest choice for your team.

The clear advantage of migrating history is the ability to immediately benefit from all of the history your team has been putting into the version control system over time. Source code history can be extremely valuable when you need to determine how long a change has been included in the product, how it was first introduced, or who introduced it.

Another advantage of moving the history to Team Foundation Server is the ability to take the legacy servers that housed the existing source code out of commission. Not having to support two separate systems can definitely be a strong benefit for some teams in terms of maintenance, cost savings, and licensing cost savings.

However, there are possible downsides to migrating the source code history into a new system such as Team Foundation Server. Following are some of those downsides:

· Testing—Migrations should be treated like any type of software development project. Time and effort should be dedicated to testing the migration numerous times in a test environment to ensure that the migration occurs exactly as planned and the end-result is what you expect.

· Third-party purchase—It is possible that the team may want to leverage a third-party migration tool that is commercially available. This involves purchasing a license and a potential support contract for help from the vendor when using the migration tool.

· Custom software development—It is also possible that a custom tool or Team Foundation Server Integration Platform adapter will need to be developed and tested. This is particularly the case whenever a tool is not available commercially.

· Playback execution time—In addition to planning, development, and testing time as part of a migration effort, you must also consider the amount of time it will take to actually play back all of the history into Team Foundation Server. Essentially, each action that has ever occurred in the legacy version control system must be committed in sequence into Team Foundation Server.

Ultimately, the return on investment for moving the source code history should be determined and weighed against the downside. If the team does end up moving over only the tip version, it can always leave around the legacy version control system in a read-only state to allow team members to research history in the archive if needed.


For more information about this particular topic, the hosts of the Developer Smackdown podcast and their guest, Ed Blankenship, discuss Team Foundation Server Migrations. This episode is available as an mp3 download athttp://aka.ms/EdPodcastMigration.

Migrating from Visual SourceSafe

If a team is currently using Microsoft Visual SourceSafe (VSS), then it is in luck. Team Foundation Server 2013 includes a streamlined VSS Upgrade Wizard that will take a VSS repository and migrate it into a team project in Team Foundation Server or Visual Studio Online.

Where Did VSSConverter.exe Go?

In Team Foundation Server 2012, the VSSConverter.exe tool was updated and renamed to VssUpgrade.exe. Unlike the VSS Upgrade Wizard, which is designed to streamline the most common upgrade scenario, this tool allows a much finer grain of control.

This tool includes several features that the wizard does not currently support, including the following:

· Move entire repository or only specified folders.

· Map locations from the legacy repository to new locations in the Team Foundation Server version control repository.

· Analyze the VSS repository for corruption and other migration issues before migration begins.

· Map VSS users to Active Directory (AD) domain user accounts.

· Update source control bindings during migration from VSS bindings to the appropriate Team Foundation Server bindings in the Visual Studio solution and projects.

The link in the Visual SourceSafe Upgrade section of the Team Foundation Server 2013 Administration Console links to the Visual SourceSafe Upgrade Tool page that is compatible with Team Foundation Server 2010, 2012, and 2013. As of this writing, the page does not explicitly state compatibility with Team Foundation Server 2013.

For more information on the VssUpgrade.exe utility which also supports Team Foundation Server 2013, see http://aka.ms/Tfs2012VSSUpgrade.


Microsoft Visual SourceSafe 2005 Standard Edition mainstream support ended July 10, 2012. When Microsoft ends mainstream support for a product, it ceases to release non-security hotfixes, provide telephone support, and supply other mainstream support options. Certain extended support options may be available to some companies for some of the benefits, but such companies must have acted within 90 days from the end of mainstream support to take advantage of them. The most up-to-date information about the support life cycle for Visual SourceSafe 2005 is available at http://aka.ms/SupportVSS. A company can also contact its Microsoft representative to inquire further about support options after mainstream support ended.

The VSS Upgrade Wizard plays back each of the check-ins into Team Foundation Server during the migration. It does so by creating changesets of files that were checked in at relatively the same time by the same user and with the same comment. Also, the changes must not conflict with one another to be included in the same changeset. For example, if a user added a specific file and then deleted it in the relatively same time period, then those two actions will not be committed in the same changeset during migration.

One of the outcomes that will be noticed is that the date and timestamp for the new changesets will be set to the time that the migration action actually occurred, instead of the original time. The original check-in date and timestamp will be stored in the changeset's comment for reference purposes. Additionally, the original user will not be stored in the comment if that user is not mapped appropriately. If the user is mapped appropriately, the user name will be in the changeset's user name field.

This section examines the different options that teams have available if they want to migrate the full history from VSS into the Team Foundation Server version control repository.

Preparing to Use the VSS Upgrade Wizard

The very first step before attempting to begin a migration effort is to ensure that the VSS repository has been fully backed up. This provides the ability to restore it to its original state if there are any errors that occur during the migration. Be sure to always run the migration utility against a copy of the database, instead of against the actual database.

One key step is to ensure that, if the VSS database version is older than the latest version (Visual SourceSafe 2005) then the database should be upgraded before the migration occurs. The DDUPD utility can be used for upgrading to the latest version after installing Visual SourceSafe 2005.

A second important step before starting the wizard is to run the Visual SourceSafe ANALYZE utility on your VSS repository. This will check the integrity and fix any structural errors.


More information on the VSS ANALYZE utility can be found at http://aka.ms/VssAnalyze.

Your development team may choose to not migrate all of the history stored in the VSS repository and instead choose to migrate only a subset of that history. Your team might decide that it only needs the last year's history to reduce the amount of migration execution time needed. If that is the case, the administrator should use the archive functionality available in VSS to archive all content before the selected date.


Using the archive functionality in VSS will permanently remove the source code and history specified. Be sure to back up the VSS database before taking this step if you need to keep that data.

For those instances where migration execution time needs to be minimized as much as possible, ensure that all of the servers and computers needed in the migration exist on the same local network or even on the same network switch. The servers and computers that will be used in the migration effort are the migration computer that will be executing the VSS Upgrade Wizard, the server hosting the file share that contains the VSS database, and the Team Foundation Server.

Finally, prepare the team for the migration by informing it of the timeframe when the migration will occur. For example, some teams will start a migration at the close of business on Friday so that the migration can be executed during the weekend, and the new location will be available by the beginning of the business day on Monday. Ideally, the team will have checked in all files, removed any check-outs, and not used the VSS database while the migration is occurring. To ensure that only the upgrade wizard has access to the repository, permissions can be removed from the file share for all users except the account that will be executing the migration.

Using the Visual SourceSafe Upgrade Wizard

Once you are ready to migrate, the first step is to download and install the latest copy of the wizard. To do that, open the Team Foundation Server Administration Console and navigate to Additional Tools and Components, and then navigate to the Visual SourceSafe Upgrade. On the right, you should see a link to download and install the latest version, as shown in Figure 9.1.


Figure 9.1 Visual SourceSafe Upgrade in the Administration Console

Once you have downloaded the wizard, run tfs_VssUpgrade.exe to start the installer. The installation wizard screen will appear and ask you for an installation path and to accept the license terms and conditions, as shown in Figure 9.2. Click Install to continue.


Figure 9.2 VSS Upgrade Installer


To streamline the process further, the installer contains a copy of the Visual SourceSafe object model. This means that there is no need to have Visual SourceSafe or other prerequisites already installed on the machine from which you are performing the migration.

Once the wizard is installed, it can be launched from the Start menu under Microsoft Visual Studio 2012 Team Foundation Server Tools VSS Upgrade Wizard, or by running VssToTfs.exe from the installation path. (The default path is C:\Program Files (x86)\Microsoft Visual SourceSafe Upgrade\VssToTfs.exe.)

On the wizard welcome screen, you need to provide the following information:

· Visual SourceSafe Repository—The folder that contains the srcsafe.ini file

· Visual SourceSafe Admin password (optional)—The password for the administrator account of your repository

Once you have specified a valid repository, you can click the List Available Projects link to attempt to load the repository and enumerate the projects, as shown in Figure 9.3. When you are ready, click Next.


Figure 9.3 VSS Upgrade Wizard options screen

The following screen (see Figure 9.4) asks you for a destination team project. The destination team project can be a local Team Foundation Server instance or Visual Studio Online. It is required that this team project does not contain any existing source code folders. Click the Browse button to select an appropriate destination. Click Next to proceed to the upgrade options screen.


Figure 9.4 Target team project screen

The upgrade options screen (see Figure 9.5) allows you to choose the fidelity of the upgrade. There are two options:

· Full history—Migrate all changes back to the very first commit.Figure 9.5 Upgrade options screenimage

· Tip—Migrate only the latest version of each file.

The VSS Upgrade Wizard also requires a SQL Server instance for temporary storage during the upgrade process. It is best if this SQL Server instance is local or close to the upgrade wizard machine. This minimizes the latency and ensures that the migration can proceed as fast as possible.

Once you have selected an upgrade option and a valid SQL Instance, select Next. After performing a series of readiness checks, click Next to start the upgrade process. The time the wizard takes to run will depend upon the options that you chose and how many changes there are. The wizard shows the progress and the current actions being performed, as shown in Figure 9.6.


Figure 9.6 Upgrade progress screen

Once the upgrade process is complete, you will be able to view an Upgrade Report. This report details the migration settings—the number of changes, files, and folders migrated. The report will also display any warnings or problems that were encountered. You can see an example of the report in Figure 9.7.


Figure 9.7 Upgrade Report

One of the limitations of the upgrade wizard is that the date-timestamp for the changesets in Team Foundation Server will be the time the migration occurred, rather than the original check-in time. However, as you can see in Figure 9.8, the original VSS commit time is preserved in the comments of the changeset.


Figure 9.8 View history dialog box showing the original VSS timestamps

Team Foundation Server Integration Platform

The Team Foundation Server product team at Microsoft has dedicated resources for creating a platform called the Team Foundation Server Integration Platform, which enables customers to build migration and synchronization tools. It is essentially an entire framework that includes a user interface (UI) for configuring the migration/synchronization run, a service for executing the actions, and even a conflict resolution experience for situations when the tool is unable to handle migration/synchronization actions.

Microsoft has provided the free utility and source code on a dedicated CodePlex project site at http://tfsintegration.codeplex.com/. Occasional updates are uploaded to the CodePlex project site, and the Visual Studio ALM Rangers have created quite a bit of documentation that is available to get you started. Figure 9.9 shows a screenshot of the Team Foundation Server Integration Platform configuration utility.


As of this writing, the Team Foundation Server Integration Platform has not been recompiled against the 2013 object model. However, the 2012 Integration Platform is fully compatible with Team Foundation Server 2013. To use it you must install either Team Explorer 2012 or the Team Foundation Server 2012 Object Model Installer on the machine hosting the Integration Platform. The Object Model Installer can be found at http://aka.ms/TFS2012OMInstaller.


Figure 9.9 Team Foundation Server Integration Platform configuration utility

The Team Foundation Server Integration Platform can assist with migrating both version control artifacts and work items from legacy systems to Team Foundation Server using an adapter system. The Team Foundation Server adapters have been created, and all that you need to do is create a version control or work-item tracking adapter for the legacy system.

Examples for creating custom adapters, as well as other adapters, are available out of the box. Following are some of the adapters that were available as of this writing:

· Team Foundation Server 2008, 2010, and 2012 Version Control

· Team Foundation Server 2008, 2010, and 2012 Work Item Tracking

· Rational ClearCase

· Rational ClearQuest

· SharePoint List

· SharePoint Document Library

· File System

If the system you want to migrate from is a custom in-house system, you can create a custom adapter using the API available in the Team Foundation Server Integration Platform. There are samples of both types of adapters available in the source code for the Team Foundation Server Integration Platform to get you started.


As mentioned earlier in the chapter, some items are not migrated when using the tool, and this should be taken into consideration when deciding on whether the tools meet your requirements. The following artifacts are not migrated by the built-in adapters:

· Permissions

· Labels

· Shelvesets

· Work item queries

· File encodings

· Pending changes

· Check-in notes

· Workspaces

· Subscriptions

· Test cases

· Check-in policies

· Reports

· Team portal

· Process templates

· Builds

· Warehouse data

Popular Third-Party Migration Tools

Several third-party tools are available commercially that can be used by teams that don't have a tool available for them or don't feel like building a custom adapter for the Team Foundation Server Integration Platform. Let's take a look at a couple of them.

Subversion, CVS, and StarTeam

The team at Timely Migration has built a tool that is very successful at migrating source code history from a Subversion (SVN) repository to Team Foundation Server. It handles many common situations, such as migrating full or selected history, discovering branches and creating them in Team Foundation Server, and converting tags into Team Foundation Server version control labels.

In addition to SVN, the Timely Migration tool supports migrating from a CVS or StarTeam repository with similar features as the SVN migration tool.


For more information about the Timely Migration tool, visit the website at http://aka.ms/TimelyMigration. There is a charge for the tool, as well as any support hours needed during the test and actual migration execution runs. You can download a trial version of the tool, which is a fully featured evaluation edition that allows you to test migrations before purchasing the product. However, it obscures the contents of each file when it is checked in to Team Foundation Server.


Thankfully, the Team Foundation Server Integration Platform includes an adapter that will allow teams to migrate from an IBM Rational ClearCase source control repository to Team Foundation Server. You can choose to migrate either full history or selected history with the available adapters.

More information about the Team Foundation Server Integration Platform was presented earlier in this chapter.


You can also use Team Foundation Server Integration Tools, which has a compiled copy of the platform and is the minimally necessary tool for migrating from ClearQuest. The Integration Tools release can be located in the Visual Studio Gallery athttp://aka.ms/TFSIP.


Migrating source code from a legacy system can be a tough endeavor for administrators and teams. This chapter reviewed the different techniques and tools necessary for migrating from a legacy system, whether that be using the new Visual SourceSafe Upgrade Wizard, the Team Foundation Server Integration Platform on CodePlex, or one of the popular third-party commercial tools. You also learned about some suggestions for ensuring a smooth migration no matter which legacy source control system your team has been using.

In Chapter 10, you will learn about the branching and merging features available in Team Foundation Server Version Control. You will learn about the new branching and track changes visualization tools, as well as some common best practices for branching and merging strategies.