TN0008: Planning Guide for Importing from Subversion and CVS

Authors: Paul Vanderlei, Michael Valenta, Jean-Michel Lemieux
Last Updated: May 5th, 2011
Build basis: Rational Team Concert 2.0, 3.0

Summary

Switching from one source control or issue tracking system to another can be a daunting task. Not only do you need to learn the new system, but you need to find a way to retain as much of the history of your project as you can. This document is intended to address the various issues regarding importing from existing source control repositories and bug tracking systems in deploying Rational Team Concert. It presents various scenarios and makes recommendations on appropriateness. Specifically, it covers the issues and options associated with importing from an existing Subversion, CVS or other version control repository into Jazz Source Control. The purpose of this document is to help you decide on an appropriate strategy for source control import; as such, this document does not cover the specific details of the actual import, since those are covered in the online documentation.

More Information

Importing from Subversion

This section lists the important aspects to consider when importing from Subversion into Rational Team Concert. Before starting the import ensure that the user running the import has a developer Client Access License and has the JazzAdmin repository permission.

Selecting Which Data to Import

The first item to consider is just what subset of your Subversion data you really need to import. Your first impulse may be to assume that you need to import everything, but often upon deeper investigation, you might find that you do not actually need all the branches and tags.

For example, if you are making the transition to Rational Team Concert at a stable point on your project, you may decide to bring over the history of your main branch. In this case, the import will be significantly faster. After the import you’ll still have all the history from your main branch including all the tags on that branch. You just won’t have the history for all the other branches.

This is also an opportunity to consider which artifacts from your Subversion repository really do need to be migrated. In many cases, you might not need all the folders, build result binaries and other data that has been accumulating over time but is no longer being used. This many be a good time to clean up by leaving the historical data in Subversion and importing into Rational Team Concert only the source code that you are actively developing.

Mapping Users

The import wizard can create users on Rational Team Concert for the users it encounters in the Subversion repository. Nevertheless, it is a good practice to create all the users from your Subversion repository as users on your Jazz Team Server before beginning the import. These users are not required to have login rights—that is, they need not have an entry in the Tomcat registry or in LDAP. If the user IDs match, then the import will automatically map ownership to the corresponding user ID in the Jazz Team Server. If you have already created different user IDs in the Jazz Team Server, you can manually map the users during the import. Remember that to create new users you must be logged in with JazzAdmin privileges.

Mapping Subversion Folders to Jazz Components

If you want to start using multiple Jazz components to split your development across different teams, you should create the teams and components in Jazz prior to the import. Then during the import, select the Subversion folders to map to the corresponding Jazz components. You’ll have to run a separate import for each Jazz component. Don’t worry too much about getting the folder mapping exactly right, since you can always move folders between components after the import.

The Subversion import wizard allows you to select a subset of the folders in the repository to be imported. However, the wizard still needs to process the entire dump file to extract the desired data. If necessary, it is possible to reduce the size of the dump file using the svndumpfilter utility. Refer to http://svnbook.red-bean.com/en/1.1/ch05s03.html for more information.

The import wizard supports creating baselines for tag and branch points and the wizard can be run again after the main development line is imported in order to import additional branches. It is also worth noting that the importer is optimized for the standard repository layout, so importing repositories with a non-standard layout consumes more memory and might not properly handle branches and tags.

You should not import multiple tags and branches in a single import into the same component. This is because in an SVN repository, branches and tags are lightweight copies of the original tree. However, Jazz uses a component/stream model to represent different lines of development. If you want to import multiple branches, you should import each branch into a separate workspace. Importing of branches is described in more detail in the documentation.

Selecting the Appropriate Database

If you are importing a large code base, it is recommended that you use a supported commercial database instead of Apache Derby. Testing has shown that when history is longer than five years or when there are more than 15,000 files in the latest configuration, the commercial databases provide significantly faster import as well as support for more concurrent users after the import.

Time Considerations

There are several factors that affect the time it takes to import a Subversion repository: the number of files, their size and the number of revisions. Keep in mind that the import is split into two phases, the first is the generation of the Subversion dump file and the second is the actual import into Jazz. Running the Subversion repository and the Jazz Team Server on the same machine can also help to minimize the time required for the import.

The following table summarizes some specific examples of various Subversion repositories and the time it took to import them to a Jazz Team Server:

Restarting the Import

Imports can stop prematurely for a variety of reasons such as running out of disk space or an intermittent communications failure. In some cases you may decide for some reason to stop an import after it has started. In any case, simply restart the import from the wizard, and when the import begins again it will detect which revisions have already been imported. Make sure to make all the same selections in the Wizard except one: you must select the component that was created during the first import.

Importing from CVS

Rational Team Concert supports importing a single branch only from a CVS repository. This means that if you do want to import tags and branches, you must first export the CVS repository into a Subversion dump file. From there, Rational Team Concert can perform a full import as described above in the Subversion section. See http://cvs2svn.tigris.org/ for more details on converting from CVS to Subversion.

Importing from Other Source Control Systems

One final option that may prove useful in many cases is to simply check out your project from any existing version control repository and load it into an Eclipse workspace. From there, you can disconnect the projects from any existing version control system and re-share the projects to Jazz Source Control. From that point onward, you can retain the project history in the original version control system and use Jazz Source Control on all new work. You can repeat this procedure for as many tags as you wish, manually creating a baseline for each tag as it is imported into Jazz Source Control. This can be useful in the situation where the project is simple enough and there is no urgent need to have the full history on Rational Team Concert. It also makes sense for evaluation projects, since you can check the projects back into the original version control system upon completion of the evaluation if you need to. In the case of version control systems that cannot be converted into a Subversion dump file, this may be the only option.

References

There is additional information about Subversion import and co-existance in the online help. See Rational Team Concert and Subversion.

Copyright © 2011 IBM Corporation