From AccuRev to Rational Team Concert

How to migrate source code

Learn how to migrate source code stored in an AccuRev repository to IBM® Rational Team Concert™ by using one of two approaches: Migrate the source code without history or migrate the source code with history. If you use AccuRev and need to migrate code to Rational Team Concert, these migration tips can help.

Share:

HimaBindu Makam (himmakam@in.ibm.com), Software Build Architect, IBM

HimaBindu Makam photoHimaBindu is a Build Architect with the business-to-business and commerce team at IBM. She has eleven years of experience working with source code tools such as AccuRev, Visual Source Safe (VSS), and IBM Rational Team Concert and installer tools such as IBM Installation Manager, InstallAnywhere, and Ant Installer. She has migrated many tools from VSS to AccuRev and from AccuRev to Rational Team Concert. She has also migrated installer tools from InstallAnywhere to Ant Installer and from Ant Installer to IBM Installation Manager.



20 May 2014

Also available in Russian

Overview

Software configuration management systems are essentially databases that provide version control for stored elements. However, because of differences in functions and internal database organization, migrating from one software configuration management system to another is rarely a simple process.

IBM® Rational Team Concert™ integrates source control with other tools such as defect management and requirements management. This article describes how to migrate source code from an AccuRev repository to Rational Team Concert with the source file history or without. Source code in this context means the code for the software that is under development, rather than the binary files for AccuRev or Rational Team Concert.

Before you proceed, determine whether you need to migrate source file history. When you are migrating a large quantity of source code, as in the case of a large AccuRev depot, you might choose to migrate the source code only, without the history that shows which files have been updated and what changes were made. This article describes how to migrate source code from AccuRev to Rational Team Concert without source file history and with source file history.

Stream design in AccuRev

To understand how streams are designed in AccuRev, consider a sample product, ANT, which you start to develop. In the beginning, the product design in the AccuRev depot is simple, as shown in Figure 1. The ANT 1.0 files are located in the Next2Ship_Build stream. Developers create their workspaces off of this stream. Builds are performed from the Next2Ship_Build stream.

Figure 1. Sample stream for ANT in AccuRev
Sample AccuRev stream

After a few months, ANT 1.0 is ready for release. The release engineer creates a snapshot from the Next2Ship_Build stream as shown in Figure 2 with a circle labeled v1.0_RTM. The release engineer then creates a new build stream v1.0_Build off of the snapshot and this is used to maintain ANT 1.0.

At this point, development starts for ANT 2.0, in the Next2Ship_Build stream. After a few months, ANT 2.0 is ready for release. The release engineer creates a snapshot from the Next2Ship_Build, as shown in Figure 2, with a circle labeled v2.0_RTM. The release engineer then creates a new build stream v2.0_Build off of the snapshot and this is used to maintain ANT 2.0.

Figure 2. Multiple streams for ANT in AccuRev
AccuRev multiple streams

Migrate source code files without history

Note: This article assumes that a Rational Team Concert project with streams, and workspace have already been created.

To migrate files to Rational Team Concert without including the source file history, follow these steps:

  1. Create a project in Rational Team Concert with the required template and create a stream RTC_Stream in that project. Streams are containers for components which, in turn, are containers for version-controlled artifacts.
  2. Create a workspace out of the RTC_Stream stream.
  3. Get the files from the v1.0_RTM snapshot in AccuRev, copy them to the Rational Team Concert workspace, and deliver them to this RTC_Stream.
  4. Create a snapshot v1.0_RTM from the RTC_Stream.
  5. Get the files from the v2.0_RTM snapshot in AccuRev, copy them to the Rational Team Concert workspace, and deliver them to this RTC_Stream.
  6. You can see outgoing changes for the new and modified files.
  7. For deleted files, you need to compare the AccuRev and Rational Team Concert workspaces, identify the files that are not in AccuRev workspace as the deleted ones, and remove them manually from Rational Team Concert workspace. Ensure that the outgoing changes include all of the new and deleted files. When the changes get processed, the Rational Team Concert workspace will be the same as the AccuRev workspace. When you finish this step, v2.0_RTM snapshot is successfully migrated.
  8. Repeat Steps 5, 6, and 7 steps for the main stream Next2Ship_Build.
  9. Repeat this process for the v1.0_Build and v2.0 Build streams.
  10. Continue the same process for any additional streams.
  11. Compare the AccuRev and Rational Team Concert workspaces for all the streams and to ensure that they are in sync.

After you finish these steps, the source code files are migrated from the AccuRev depot to a Rational Team Concert project area. However, the source file history that was tracked in AccuRev is not migrated. The source file history is lost, if you use this method.

The rest of this article describes how to migrate source code files while retaining history.


Migrate source code files with history

To retain the source file history, you need to re-create AccuRev depots as Rational Team Concert project areas. The goal is for each project area to match the AccuRev depot in terms of:

  • Stream hierarchy
  • Stream content
  • Snapshots

When you re-create AccuRev depots as Rational Team Concert project areas, the change history from the AccuRev system is maintained, current development practices remain unchanged, and access rights and permissions are preserved. Although the migration is performed with minimal impact to the developers, it is not possible to migrate developer workspaces from AccuRev to Rational Team Concert.

To migrate source code files and retain their history, use the design shown in Figure 3 and follow the workflow to create a migration system.

Figure 3. Migration system block diagram
Block diagram to represent the migration flow

The migration system shown in Figure 3 includes the following major components.

ComponentDescription
AccuRev serverMachine that hosts the AccuRev source repository.
Source client machineMachine with network access to the AccuRev server.
AccuRev clientApplication that runs on the source client machine. It provides the user interface to the AccuRev repository. Users can choose either a GUI or a command-line interface.
Source agentCustom-built application that runs on the source client machine. It has access to the AccuRev repository through the command-line interface provided by the AccuRev client.
MailboxFolder in a shared file system that is used to pass packages from the source agent to the target agent.
PackageData structure that completely defines any AccuRev repository update.
Jazz serverMachine that hosts the target (Rational Team Concert) repository.
Target client machineMachine with network access to the Jazz server.
Rational Team Concert Java APISet of Java classes that enables Rational Team Concert operations to be scripted.
Target agentCustom-built application that runs on the target client machine. It has access to the Rational Team Concert repository through the Rational Team Concert Java API.

Workflow to migrate an AccuRev depot

Use the following workflow to build a migration system that migrates an AccuRev depot to a Rational Team Concert project:

  1. The user instructs the source agent to migrate a specific AccuRev depot.
  2. The source agent uses the AccuRev client to obtain the depot history. The depot history is a time-ordered list of AccuRev transactions that have been applied to the depot.
  3. The source agent cycles through the depot history and creates packages that are placed into the depot mailbox.
  4. Each package describes one or more generic transactions and contains any required supporting material, such as specific file versions.
  5. The user instructs the target agent to monitor a specific depot mailbox.
  6. The target agent processes the packages in the depot mailbox in the order that they were created.
  7. The target agent creates the Rational Team Concert project area when it processes the first package.
  8. The target agent cycles through each package and translates the generic transactions into Rational Team Concert transactions and applies them to the Rational Team Concert project area.

The system scales to make it possible to do parallel migration of multiple AccuRev depots.

The workflow process continues until the source and target agents are stopped. In this way, the migration system gradually synchronizes the Rational Team Concert project area with the AccuRev depot and then keeps it in sync.


Description of a package

A package is the unit of communication between the source agent and the target agent. Each package describes one or more generic transactions. As shown in Figure 4, a package is a folder in a shared file system. Folder names are in the form Pkg-nnnnn, where nnnnn is an ascending sequence number. This naming convention makes it possible for packages to be processed in the order they were created.

Figure 4. package structure
Sample package with transaction folders

Each package contains a package description file and potentially, transaction folders.

The package description file description.xml is found in the package root folder Pkg-nnnnn. The basic structure of this file is:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<package>
 // package body
</package>"
  • Package body: Consists of one or more transaction descriptors. These are XML structures that define operations on a repository. Each transaction descriptor has a unique time stamp and transaction ID.
  • Transaction descriptors: Listed in the package description file in time-stamp order (oldest first).
  • Transaction ID: Specifies the transaction folder where any file content associated with the transaction can be found.
  • Transaction folder: Contains a sparse directory tree. Only the folders and files associated with the transaction are included.

Transaction descriptor

The source agent processes AccuRev transactions to create generic transactions. The target agent processes generic transactions to run Rational Team Concert transactions. A transaction descriptor represents a generic transaction. It is an XML structure that fully defines an atomic operation on a repository. The following code listing shows the basic transaction descriptor syntax. The brackets [ ] enclose optional tags.

<transaction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance
"xsi:type="streamData" user="AccuRev" type="xxxxxxxx"
timeStamp="1129138647" id="1.0">
//Transaction body
</transaction>

The transaction header includes the following tags. The tags xmlns and xsi can be ignored.

  • id: Uniquely identifies the transaction. It is a decimal number.
  • timeStamp: Identifies the time at which this transaction occurred in the source repository. It is a 10-digit value.
  • user: Specifies the user ID that is responsible for this transaction in the source repository.
  • type: Specifies the transaction structure. It determines which additional tags can be found in the transaction header and the structure of the transaction body.
  • comment: Text is optional.

Generic transactions

Many transaction descriptors in the package description file have no body. These represent AccuRev transactions that have been found in the depot history but are not needed for the migration. Only operations on a stream are relevant to migration.

Generic transactions are of four types:

  • chstream
  • mkstream
  • purge
  • promote
    • defunct
    • keep
    • move
    • undefunct

The following syntax is used for all types. The brackets [ ] enclose optional elements.

chstream: Changes the attributes of a stream

<transaction type="chstream"
<streamID>10</streamID> <streamName>TestSCM-SqlServer</streamName> [<oldStreamName>TestSCM-SqlServer</oldStreamName>] <baseStreamName>TestSCM</baseStreamName> [<baseStreamType>normal</baseStreamType>] <isHidden>false</isHidden> <streamType>workspace</streamType> <basisTime>0</basisTime> </transaction>
  • <streamID>: Unique handle assigned to the stream by AccuRev
  • <oldStreamName>: Not required if the <streamType> is workspace.
  • <baseStreamType>: Not required if the <streamType> is workspace.

mkstream: Creates a new stream

<transaction type="mkstream" 
                <streamID>1</streamID>
                <streamName>TestSCM</streamName>
                <isHidden>false</isHidden> Ok
                <streamType>normal</streamType> 
                <basisTime>0</basisTime> 
</transaction>
  • <streamID>: Unique handle assigned to the stream by AccuRev.
  • <streamType>: Can be normal, pass through, or workspace.

purge: Restores elements to the version last entered into the stream

<transaction type="purge"
                <streamName>TestSCM_SanMateo</streamName> 
                <streamType>normal</streamType> 
                <baseStreamName>TestSCM</baseStreamName> 
                <baseStreamType>normal</baseStreamType> 
                <file>
<fileId>49127</fileId> <isDirectory>true</isDirectory> <path>\Purge_rename</path> <sequenceId>51.0</sequenceId> <fileStatus>keep</fileStatus> <comment>purged file</comment> <defectID>123</defectID> </file> </transaction>
  • <file>: Identifies a subject element. This can be repeated for multiple elements.
  • <fileStatus>: Identifies the operation on the element.
  • <comment> and <defectID>: Information is inserted into the Rational Team Concert file properties and the Change Set comment.

promote: Sends changes from one stream to another

The promote operation includes four subtypes. A single promote transaction can have any number and any mixture of these subtypes.

  • defunct
  • move
  • keep
  • undefunct

promote (defunct): Removes an element from version control

 <transaction type="promote">
                <toStream>TestSCM</toStream>
<file> <fileId>192</fileId> <isDirectory>true</isDirectory> <path>\HotfixComponents\Database\db2</path> <sequenceId>23.0</sequenceId> <fileStatus>defunct</fileStatus> [<comment>Example defunct</comment>] [<defectID>123</defectID>] </file> </transaction>
  • <file>: Identifies the subject element.
  • <fileStatus>: Identifies the operation on the element.
  • <comment>: Information is inserted into the Rational Team Concert file properties and the Change Set comment.
  • <defectID>: Information is inserted into the Rational Team Concert file properties and the Change Set comment.

promote (move): Renames or relocates elements within the source directory tree

<transaction type="promote" >
                <file>
                <fileId>254</fileId> 
                <isDirectory>true</isDirectory> 
                <path>\HotfixComponents\Database\oracle\scripts</path> 
                <source>\HotfixComponents\Database\oracle\scripts-kmd</source>
                <destination>\HotfixComponents\Database\oracle\scripts</destination>
                <sequenceId>39.0</sequenceId> 
                <fileStatus>move</fileStatus> 
                <comment>defunct</comment>
                <defectID>123</defectID>
                </file>
                <toStream>TestSCM</toStream>
                fromStream>Where</fromStream> 
</transaction>
  • <file>: Identifies the subject element.
  • <fileStatus>: Identifies the operation on the element.
  • <comment>: Information is inserted into the Rational Team Concert file properties and the Change Set comment.
  • <defectID>: Information is inserted into the Rational Team Concert file properties and the Change Set comment.

promote (keep): Provides a new version of an element

<transaction type="promote">
                <toStream>TestSCM</toStream> 
                <file>
                <fileId>264</fileId> 
                <isDirectory>false</isDirectory> 
                <path>\HotfixComponents\Database\sqlserver\scripts\yfs_table_not_sized_73_HF16.sql
                </path> 
                <sequenceId>41.0</sequenceId> 
                <fileStatus>keep</fileStatus> 
                <mergedAgainstStreamName>TestSCM</mergedAgainstStreamName>
                <mergedAgainstStreamType>normal</mergedAgainstStreamType>
                <mergedAgainstBaseStreamName>TestSCM</mergedAgainstBaseStreamName>
                <mergedAgainstBaseStreamType>normal</mergedAgainstBaseStreamType>
                <comment>defunct</comment>]
                <defectID>123</defectID>
                </file>
</transaction>
  • <file>: Identifies the subject element.
  • <fileStatus>: Identifies the operation on the element.
  • <mergedAgainst...>: Indicates the artifact has been created by a merge.
  • <mergedAgainstBase...>: Indicates the base used for the merge (ancestor).
  • <comment>: Information is inserted into the Rational Team Concert file properties and the Change Set comment.
  • <defectID>: Information is inserted into the Rational Team Concert file properties and the Change Set comment.

promote (undefunct): Restores version control for the named element

<transaction type="promote">
                <toStream>TestSCM</toStream> 
                <fromStream>TestSCM</fromStream>
                <file>
                <fileId>44604</fileId> 
                <isDirectory>false</isDirectory> 
                <path>\buildallmigration.xml</path> 
                <sequenceId>1401.0</sequenceId> 
                <fileStatus>undefunct</fileStatus>  
                </file>
</transaction>
  • <file>: Identifies the subject element.
  • <fileStatus>: Identifies the operation on the element.

Properties files

All properties files are simple text files. Lines starting with # are comment. The source agent and the target agent use different syntax for the properties files.

Source agent properties file

The properties file defines major operational parameters for the source agent. It must be in the same folder as the source agent executable. The syntax is illustrated by the following example.

#
# File system path to mailbox
# mailbox_dir=<full path to mailbox directory>
mailbox_dir=C:\\mailbox\\
#
# Maximum number of transactions per package
# transactions_per_package=<transaction max>>
transactions_per_package=100
#
# folders to exclude from the migration
Foundation_folders_to_exclude=\\this\\, \\that\\, \\the_other\\
#
# How often to check a migrated depot for new transactions
# refresh_transaction_mins=<period>
refresh_transaction_mins=5
#
# Who to send e-mail notifications to?
# email_receivers=<email addr>[, <email_addr> …]
email_receivers=person1@in.ibm.com,person2@us.ibm.com
#
# The level of log messages to be logged for each depot migration. This property 
# will not affect the common logger level which is always set to ALL.
# logging_level=<ALL | FINE | INFO | WARNING | SEVERE>
logging_level=INFO
#
# The number of log files to write before rolling over (must be at least 1)
# log_file_count=<number of files>
log_file_count=50
#
# The maximum size of each log file in bytes (must be at least 0)
# log_file_size=<size of bytes>
log_file_size=500000

Target agent properties file

This file defines major operational parameters for the target agent. It must be in the same folder as the target agent executable. The syntax is illustrated by the following example.

#
# Connection information for the Jazz Server
# rtc_repository_Address=<jazz repository URI>
# rtc_username=<userID>
# rtc_password=<password>
rtc_repository_Address=https\://jazz705.hursley.ibm.com\:9443/ccm
rtc_username=Y9AB2Y866@nomail.relay.ibm.com
rtc_password=xxxxxxxx
#
# Scheduled down-time for the Jazz Server
# downtime=<{24 hour time}-{24 hour time}>
downtime=03:00-04:00
#
# File system path to mailbox
# mailbox_dir=<full path to mailbox directory>
mailbox_dir=C:\\mailbox\\
#
# RTC Process Template
# rtc_process_template_id=”<template>.process.ibm.com”
process_template=”scrum2.process.ibm.com”
#
# How often to check for new depot mailboxes
# refresh_depots_mins=<period>
refresh_depots_mins=5
#
# How often to check a migrated depot mailbox for new packages
# refresh_transaction_mins=<period>
refresh_transaction_mins=5
#
# Who to send e-mail notifications to?
# email_receivers=<email addr>[, <email_addr> …]
email_receivers=person1@in.ibm.com,person2@us.ibm.com
#
# The level of log messages to be logged for each depot migration. This property 
# will not affect the common logger level which is always set to ALL.
# logging_level=<ALL | FINE | INFO | WARNING | SEVERE>
logging_level=INFO
#
# The number of log files to write before rolling over (must be at least 1)
# log_file_count=<number of files>
log_file_count=50
#
# The maximum size of each log file in bytes (must be at least 0)
# log_file_size=<size of bytes>
log_file_size=500000

The source and target agents both create log files. These are saved in the same shared file system as the mailbox. Entries in the log files have the following syntax:

{Date} {SourceClassName} {SourceMethodName} {Log Message Level} {Log Message}
  • Date: Time stamp (date and time) for the entry.
  • SourceClassName and SourceMethodName: Identify a location in the code.
  • Log Message Level:
    • FINE: Log transactions in detail.
    • INFO: Log transactions at high level.
    • WARNING: Log non fatal errors only.
    • SEVERE: Log fatal errors only (with stack trace).
  • Log Message: Text string.

Description of the source agent

The source agent, as shown in Figure 5, is a Java application that runs on the source client machine. It is controlled through a simple user interface and with global parameters that are supplied through a properties file.

Figure 5. Depots running in the source agent
List of depots in the source agent

The source client machine must have network access to the AccuRev server. The AccuRev client must also be running on the source client machine. It must be logged in to to the AccuRev repository. The source agent properties file must be in the same directory as the executable.

The main purpose of the source agent is to create a stream of packages that contains transaction descriptors that direct the target agent in constructing a project area in the target Rational Team Concert repository.

The source agent performs this task by analyzing the AccuRev depot history, which is the sequence of AccuRev transactions that were used to construct the depot.

The source agent is capable of processing multiple depots in parallel.
Only the following AccuRev transactions are translated into transaction descriptors:

  • chstream
  • defunct
  • mkstream
  • move
  • promote
  • purge (when used on a stream)
  • undefunct

The AccuRev hist command provides the depot history. The cat command makes it possible for version-controlled elements to be extracted from the repository and added to the package.


Description of the target agent

The target agent, as shown in Figure 6, is a Java application that runs on the target client machine. It is controlled through a simple user interface and with global parameters that are supplied through a properties file.

Figure 6. Depots running in the source agent
List of depots in the source agent

The target client machine must have network access to the Rational Team Concert server. The application ID defined in the target agent properties file must be in the Rational Team Concert server and the password must be valid. The process template must be deployed on the Rational Team Concert server. The target agent properties file must be in the same directory as the executable.

The main purpose of the target agent is to sequentially process the packages that appear in a depot mailbox. The target agent is capable of processing multiple depot mailboxes in parallel. The target agent re-creates the AccuRev depot as an Rational Team Concert project area by applying the generic transactions found in the packages.

Note: The AccuRev depot name is used in the depot mailbox name. The name of the target Rational Team Concert project area is taken from the depot mailbox name. The Rational Team Concert project area therefore has the same name as the AccuRev depot. The target agent uses the Rational Team Concert Java API to synthesize an Rational Team Concert transaction from each generic transaction.


Communication between the source and target agents

The interface for all communication between the source and target agents is a shared file system folder called Mailbox, as shown in Figure 7. The mailbox contains a Logs folder and a number of depot mailbox folders.

Figure 7. MailBox
MailBox folder

Source and target client platforms

The source and target agents are platform-independent. However, they must be run on the same platform, such as Windows™ or Linux®, to avoid issues that arise from platform differences in text files such as:

  • Path separators:
    \ (Windows
    / on Linux
  • End-of-line markers:
    <CR><LF> (Windows)
    <LF> (Linux)

Coordination of source and target agents

By design, the source and target agents operate asynchronously. Coordination of the agents is a manual activity. The two user interfaces make it possible for migrations to be independently started, stopped and reset.

Independently stopping and starting a migration on either agent is not a problem. The effect of stopping a migration differs, depending on whether it is stopped at the target agent or the source agent.

  • If the migration is stopped at the target agent, the source agent will continue to add packages to the mailbox until it either completes the migration or is forced to pause because the mailbox is full.
  • If the migration is stopped at the source agent, the target agent will continue to process packages from the mailbox until the mailbox is empty.

At either agent, a migration can only be reset if it is already stopped. However, care should be taken to only reset a migration if it has been stopped at the other agent. The effect of stopping a migration differs, depending on whether it is stopped at the target agent or the source agent.

  • If the migration is reset at the source agent, the migration status becomes Resetting. Migration state variables saved in the properties file are reset, the package folders in the mailbox are cleaned up, and the migration status becomes Ready. When the migration is restarted, it processes the depot history from the beginning again.
  • If the migration is reset at the target agent, the migration status becomes Resetting. Migration state variables saved in the properties file are reset and the Rational Team Concert project area is renamed (by appending Archived and a time stamp) before being archived. The migration status is then changed to Ready. When the migration is restarted, it processes packages from the beginning again.

Email notifications

Both the source and target agent properties files contain a list of email_receivers. This is a comma separated list of e-mail addresses. The agents will send e-mails to these addresses in the event of a migration halting dues to a fatal error.


Troubleshooting source agent issues

To troubleshoot source agent issues, use the following tips and solutions.

Not all workspaces are not migrated

Workspaces might not be migrated for two reasons:

  • AccuRev workspaces have two parts. If the workspace stream exists in the repository but the workspace tree exists in the file system of the user's workstation, the workspace tree is unreachable by the migration system.
  • Every AccuRev user can have many workspaces. Because migrating all of these workspace significantly increases the migration effort, some user workspaces might not be migrated by the migration system.

If the same workstation is used to access both AccuRev and Rational Team Concert, users can migrate their own workspaces as follows:

  1. Create a Rational Team Concert workspace, which consists of a repository workspace and a personal workspace.
  2. Load the Rational Team Concert workspace from the Rational Team Concert stream that has been migrated from the AccuRev stream that backs the user's AccuRev workspace.
  3. Overwrite the artifacts in the Rational Team Concert personal workspace with the active artifacts from the AccuRev workspace tree.
  4. Check in the resultant change set.

Ignored AccuRev transactions

The source agent does not process the following types of AccuRev transaction because they are not relevant to the migration.

TransactionDescription
archiveUsed to prepare files for transfer to offline storage.
check outUsed to lock an artifact for exclusive update.
compressAlternate form for archive.
defcompThis is used to specify which files to include/exclude when updating a workspace.
dispatchUsed to pass information to AccuWork.
purgeCancels changes made in the user workspace. The source agent does handle purge when it applies to a stream.
unarchiveReverses the effect of archive.

The add, move, defunct, undefunct are processed as part of promote transactions.

Transactions occur out of order

AccuRev has a feature called TimeSafe that essentially allows the repository configuration to be reconstructed for any point in time. This means that many commands include a time spec parameter.

For example, mkstream takes a time spec, so it is possible to create a snapshot stream that contains the stream configuration at any time between the stream creation and the present moment. When the mkstream transaction goes into the depot history, it is time stamped with the current time. The time spec is provided by the basis time tag in the transaction.

Rational Team Concert does not have this feature, therefore, the source agent starts a migration by obtaining the full depot history. It performs an initial scan of the history, looking for out-of-order transactions, which are transactions where the basis time is different from the time stamp. These are stored on a FIFO list.

The source agent then starts to process the depot history. The next transaction to process is determined by comparing the time stamp of the next transaction in the depot history with the basis time of the transaction at the FIFO head. Whichever is earlier is processed.

The net effect is that the stream of transactions presented to the target agent is ordered by basis time. For the example given, the mkstream transaction is moved so that the target agent can execute it at the present moment.

Re-running a migration

During a migration, the source agent creates packages from the history of AccuRev transactions. Each package contains a package description file and a transaction folder for each transaction that updated one or more source files. The transaction folder is populated with the appropriate versions of the source files.

The extraction of specific file versions is the time-consuming element of a migration. If a migration is stopped and restarted, the package description files are regenerated. Before extracting a file version, the source agent checks the transaction folder to see if that version is already present. If it is, the extract is skipped.

This process makes the rerun migration much faster than the original migration.

Exception handling

Many exceptions can cause a migration to fail:

  • Loss of access to the mailbox folder.
  • Depot mailbox is full.
  • Loss of connectivity to the AccuRev Server.

Rather than trying to recover from all types of failure, the source agent simply logs the event and stops the migration. Manual intervention is required to restart.


Description of target agent operations

In Rational Team Concert, certain operations and attributes of the target agent are managed differently than they are in AccuRev. To accommodate the differences, configure Rational Team Concert to handle these AccuRev-specific setttings.

Application ID

The target agent operates Rational Team Concert using an application ID. Updates to the Rational Team Concert Repository made by the migration system are attributed to this user ID.

Similarly, the Rational Team Concert repository updates are time stamped according to when they are applied by the target agent.

Retention of AccuRev information

Some information from the AccuRev repository cannot be directly applied to the Rational Team Concert repository, for example:

  • AccuRev user ID responsible for a transaction.
  • AccuRev transaction ID.
  • AccuRev time stamp for a transaction.
  • The comment applied to an AccuRev transaction.
  • AccuWork issue number (or HP Quality Center record number or both) associated with a transaction.

This information is passed to the target agent in the transaction descriptor and is saved in Rational Team Concert as a Change Set comment or through file properties.

Pass-through streams

AccuRev supports a special type of stream called a pass-through stream. Changes promoted to a pass-through stream flow straight to the parent stream. Pass-through streams are mainly used to manage the stream hierarchy. Re-parenting a pass-through stream is easier than individually re-parenting all the streams and workspaces that flow into it.

Rational Team Concert does not support pass-through streams. Instead, the target agent deals with them in the following way. The mkstream transaction indicates that the stream is a pass-through. The target agent makes the stream but appends _passthrough to the stream name.

The result is that the stream appears in the Rational Team Concert project area stream hierarchy and is identified as a pass-through. This method makes it possible for it to be subsequently deleted.

Hidden streams

The AccuRev GUI makes it possible for streams to be hidden from view. This is a convenience of presentation rather than an attribute of a stream.

In Rational Team Concert, each stream has a visibility attribute. This makes the stream visible to specific Team Areas.

The migration system treats a hidden streams just like any other stream. A stream that is hidden in AccuRev becomes visible in the Rational Team Concert project area. The stream can be hidden or removed in Rational Team Concert as a post-migration activity.

Inheritance

In AccuRev, promoting an element (a file or a directory) makes it active in the target stream and inactive in the source stream or workspace. If the target stream is part of a hierarchy, the active element is immediately available to the first tier of descendent dynamic streams.

The element is automatically inherited by a descendent stream if it is inactive in that stream. After it is inherited, an element becomes active in the stream and can be inherited by the next tier of descendent streams.

Rational Team Concert does not flow changes through the stream hierarchy this way, so the target agent must mimic the AccuRev behavior. The target agent runs a generic promote transaction into a target stream as an Rational Team Concert deliver transaction. This transaction has one change set per element but the delivery is atomic.

These change sets become pending incoming changes for any stream that flows into the target stream. The target agent then inspects these streams and delivers change sets where appropriate. This process continues down the stream hierarchy.

Exception handling

The following exception conditions can cause a migration to fail.

  • Loss of access to the mailbox folder
  • Loss of connectivity to the Jazz server or to another critical service.

Rather than try to recover from all types of failure, the target agent simply logs the event and stops the migration. Manual intervention is required to re-start.


Post-migration tasks

The migration system creates and populates a Rational Team Concert project area from the information found in an AccuRev depot. All project areas are created from the same template. However, there are some aspects of the Rational Team Concert configuration that cannot be handled through a template.

  • Project area: To complete the project area configuration, it is necessary to assign project administrators and assign project members.
  • Team areas: To complete the configuration of each team area, it is necessary to assign team members.
  • Project area: To complete the project configuration, it is necesary to assign project administrators and assign project members.
  • Team area: To complete the configuration of a team area, it is necesary to assign team members.

After migration, perform the following post-migration checks on streams.

  • Does the Rational Team Concert stream hierarchy match the AccuRev stream hierarchy?
  • Does each Rational Team Concert stream have the same content as the equivalent AccuRev stream?
  • Do the outgoing change sets from each Rational Team Concert stream match the list of active files on the AccuRev stream?
  • To complete the stream hierarchy configuration:
    • Set the Rational Team Concert stream visibility and ownership attributes.
    • Delete pass-through streams (optional).
    • Delete or change ownership and visibility to the administrators team area only for the streams that are now hidden in AccuRev but present in Rational Team Concert (optional). Because there is no way to hide streams in Rational Team Concert, make sure that the flow targets are adjusted appropriately.

Conclusion

This article explained how to migrate source code from AccuRev to Rational Team Concert with and without history. It describes some differences in how streams are developed in each tool and gives steps for how to accommodate for these differences. After migration, post-migration checks ensure that the migration is successful.

Resources

Learn

Get products and technologies

  • Download Rational Team Concert from Jazz.net and try it free on up to 10 developers for as long as you want (requires registration). If you'd prefer, you can try it in the sandbox instead, without installing it on your own system.
  • Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, DevOps
ArticleID=971513
ArticleTitle=From AccuRev to Rational Team Concert
publish-date=05202014