Interstage ADM Software Configuration Management Migration ...software.fujitsu.com/jp/manual/manualfiles/M080264/... · This manual describes how to migrate projects from other software

Interstage Application and Service Management V10.0

Interstage ADM Software Configuration Management Migration Guide

B1WD-2441-01ENZ0(00)October 2008

Trademarks Interstage and Enabler are trademarks of Fujitsu Limited in Japan and/or other countries.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

UNIX is a registered trademark of the Open Group in the United States and in other countries.

Linux is a registered trademark of Linus Torvalds.

Other company names and product names are trademarks or registered trademarks of their respective owners.

Copyright © FUJITSU LIMITED 2008

All rights reserved, including those of translation into other languages. No part of this manual may be reproduced in any form whatsoever without the written permission of Fujitsu Limited.

[High Risk Activity]

The Customer acknowledges and agrees that the Product is designed, developed and manufactured as contemplated for general use, including without limitation, general office use, personal use, household use, and ordinary industrial use, but is not designed, developed and manufactured as contemplated for use accompanying fatal risks or dangers that, unless extremely high safety is secured, could lead directly to death, personal injury, severe physical damage or other loss (hereinafter "High Safety Required Use"), including without limitation, nuclear reaction control in nuclear facility, aircraft flight control, air traffic control, mass transport control, medical life support system, missile launch control in weapon system. The Customer shall not use the Product without securing the sufficient safety required for the High Safety Required Use. In addition, Fujitsu (or other affiliate's name) shall not be liable against the Customer and/or any third party for any claims or damages arising in connection with the High Safety Required Use of the Product.

Interstage ADM Software Configuration Management Migration Guide 2

Contents 1 Introduction ....................................................................... 8

2 Before the Migration ......................................................... 9

2.1 Optimizing the Project Structure.........................................................9

2.2 Migrating Large Projects......................................................................12

2.3 Preparing the SCM Environment.........................................................14

2.4 Creating a Backup ................................................................................14

3 Automated Migration ........................................................ 15

3.1 Migration in steps .................................................................................15

3.2 Preparations ..........................................................................................15 3.2.1 System Requirements.............................................................................16 3.2.2 Creating a Target Directory.....................................................................16 3.2.3 Providing Sufficient Disk Space ..............................................................17 3.2.4 Preparing the Command Line Interface Usage ......................................17 3.2.5 Considering Memory Requirements .......................................................18 3.2.6 Considering the Duration of a Migration .................................................18 3.2.7 Logging ...................................................................................................18 3.2.8 Commit comments ..................................................................................19 3.2.9 Copying the exported structure...............................................................19 3.2.10 Restrictions .............................................................................................20

3.3 Automatically Migrating CVS Projects ...............................................20 3.3.1 Preparations............................................................................................21 3.3.2 Defining the Export Target ......................................................................26 3.3.3 Defining the SCM Project Structure ........................................................27 3.3.4 Starting the Export ..................................................................................29 3.3.5 Resuming an Aborted Export..................................................................29 3.3.6 Multiple Export ........................................................................................29 3.3.7 Restrictions .............................................................................................30

3.4 Automatically Migrating VSS Projects................................................31 3.4.1 Preparations............................................................................................31 3.4.2 Defining the Project Mapping..................................................................32 3.4.3 Starting the Export ..................................................................................37 3.4.4 Error Handling .........................................................................................38 3.4.5 Resuming an Aborted Export..................................................................38 3.4.6 Restrictions .............................................................................................38


3.5 Importing into SCM...............................................................................39 3.5.1 Multiple Import.........................................................................................39 3.5.2 Creating the User Mapping .....................................................................39 3.5.3 Handling comments ................................................................................40 3.5.4 Importing the Project...............................................................................40

4 Manual Migration .............................................................. 42

4.1 Preparations ..........................................................................................42

4.2 Defining a Base Configuration ............................................................43 4.2.1 CVS Base Configuration .........................................................................44 4.2.2 RCS Base Configuration.........................................................................44 4.2.3 VSS Base Configuration .........................................................................45 4.2.4 Removing Administrative Resources......................................................47

4.3 Creating a Local Eclipse Project .........................................................47

4.4 Creating an SCM Project ......................................................................51

4.5 Defining a Release ................................................................................53

4.6 Rebuilding the Version History ...........................................................55

5 After the Migration ............................................................ 56

5.1 Setting up Roles and Authorities ........................................................56

5.2 Defining Ignored Resources ................................................................56

5.3 Creating Developer Workspaces.........................................................57

Appendix A Migration Mapping File .............................................. 59

Appendix B Environment XML Files ............................................. 64

B.1 Export Environment File ......................................................................64

B.2 Import Environment File.......................................................................65

Appendix C Migration Commands ................................................ 66



About this Manual This manual describes how to migrate projects from other software configuration management systems to SCM, the software configuration management component of Interstage Application Development Cycle Manager – hereafter referred to as Interstage ADM. Interstage ADM is a product of the Fujitsu Interstage Application and Service Management suite – hereafter referred to as Interstage ASM.

The manual is structured as follows:

Title Description

Chapter 1 Introduction Gives an introduction to the migration possibilities.

Chapter 2 Before the Migration Describes what should be considered before a new SCM project is set up as well as system requirements for migration.

Chapter 3 Automated Migration Describes the automatic migration facilities provided by SCM, and how to automatically migrate CVS and VSS projects to SCM.

Chapter 4 Manual Migration Describes how to manually migrate existing projects to SCM.

Chapter 5 After the Migration Describes the required activities after a new project has been set up in SCM.

Appendix A Migration Mapping File Describes the XML mapping file that defines how a project is mapped to SCM entities.

Appendix B Environment XML Files Describes the syntax for the environment files which are created during the SCM migration.

Appendix C Migration Commands Describes the syntax for the command line interface commands provided for the migration.

Readers of this Manual This manual is written for system administrators who want to migrate existing projects to SCM in order to put them under SCM version control.

The manual requires basic knowledge of the following:

• Using command line interfaces

• How to develop software products

• Using source code management systems including versioning and process management functionality

• The Eclipse software development environment

• Managing projects in CVS, VSS, and in SCM

Notational Conventions This manual uses the following notational conventions:

Add The names of graphical user interface elements like menu options are shown in bold case.

init System names, for example, command names, and text that is entered from the keyboard are shown in Courier font.

<variable> Variables for which values must be entered are enclosed in angle brackets.

[option] Optional items, for example, optional command options, are enclosed in square brackets.

{one | two} Alternative entries are enclosed in curly brackets and separated by a vertical bar.

Abbreviations This manual uses the following abbreviations for Interstage products and components:

Interstage ASM Interstage Application and Service Management suite

Interstage BPM Interstage Business Process Manager

Interstage ADM Interstage Application Development Cycle Manager product of Interstage ASM

Interstage SQA Interstage Software Quality Analyzer product of Interstage ASM

CHM Change Management component of Interstage ASM

COC Control Center component of Interstage ASM

DMS Document Management component of Interstage ASM

LCM Lifecycle management components (CHM, RLM, RQM) of Interstage ASM

QAM Quality Assessment component of Interstage ASM

RLM Release Management component of Interstage ASM

RQM Requirements Management component of Interstage ASM

SCA Source Code Analysis component of Interstage ASM

SCM Software Configuration Management component of Interstage ASM

The term "Windows" is used to denote the different Microsoft Windows operating systems supported by Interstage ASM.


Related Documentation Apart from this manual, the following documentation on Interstage ASM is available:

• Interstage ASM Overview: A PDF manual introducing Interstage ASM and describing its main features and basic concepts.

• Interstage ADM Installation Instructions: A PDF manual describing the installation and uninstallation of Interstage ADM.

• Interstage SQA Installation Instructions: A PDF manual describing the installation and uninstallation of Interstage SQA.

• CentraSite Installation Instructions: A PDF manual describing the installation and uninstallation of CentraSite.

• Interstage ADM Lifecycle Management User Guide: An online manual describing how to work with the lifecycle management (LCM) components of Interstage ASM from the client interface.

• Interstage ADM Software Configuration Management User Guide: An online manual describing how to work with the Software Configuration Management (SCM) component of Interstage ASM from the client interface.

• Interstage ADM Document Management User Guide: An online manual describing how to work with the Document Management (DMS) component of Interstage ASM from the client interface.

• Interstage ASM Control Center User Guide: An online manual describing how to work with the Control Center (COC) component of Interstage ASM from the client interface.

• Interstage SQA Source Code Analysis User Guide: An online manual describing how to work with the Source Code Analysis (SCA) component of Interstage ASM from the client interface.

• Interstage SQA Quality Assessment User Guide: An online manual describing how to work with the Quality Assessment (QAM) component of Interstage ASM from the client interface.

• CentraSite User Guide: An online manual describing how to work with the SOA Asset Management (CentraSite) component of Interstage ASM from the client interface.

• Interstage ASM Administration Guide: A PDF manual describing the administration and configuration of Interstage ASM.

• Interstage ASM Customization Guide: A PDF manual describing how to extend, localize and customize Interstage ASM.

• Interstage ADM Command Line Interface: A PDF manual describing the Interstage ADM command line interface.

Additionally, the following documents of Fujitsu Enabler are of relevance:

• Enabler Administration: A PDF manual describing the administration of Enabler servers and repositories.

• Enabler WebDAV Interface: A PDF manual describing how to set up the working environment for accessing files managed in a repository using WebDAV clients.


1 Introduction This document describes the steps necessary for migrating projects from other software configuration management systems including their histories to SCM. SCM supports two types of migration:

• Manual migration

• Automated migration including histories

Before any existing project can be used with SCM, its project resources must be migrated. Basically, this means that a project must be defined in an SCM repository and the resources must be taken under version control.

This manual covers the process of migrating project resources and put them under SCM version control. In addition, it provides proposals, which are important for setting up an efficient, team-oriented development process.

Most of the descriptions are independent of your existing infrastructure, i.e. whether you already use another software configuration management system or whether you start with a new project.


2 Before the Migration Before you start with the migration of a project, consider the following aspects:

• Take a look at the structure of your project. Migrating to SCM might be an occasion to optimize the project structure. For details, refer to Section 2.1, Optimizing the Project Structure.

• When you want to migrate large projects, i.e. projects having a huge number of resources (files and folders) and a highly nested folder structure, you might need to tune your Enabler system. For details, refer to Section 2.2, Migrating Large Projects.

In addition, always perform the following steps:

• Prepare the SCM environment as described in Section 2.3, Preparing the SCM Environment.

• Backup the project resources. For details, refer to Section 2.4, Creating a Backup.

2.1 Optimizing the Project Structure A well-organized project structure is crucial for developing software within a team, especially if you work with a software configuration management system. If possible, check and adapt the structure of your resources as described below before you migrate them to SCM.

Note:

If you change the project structure, be aware of the usage of absolute or relative paths that might be referred to in resource files (e.g. "makefiles").

1. Balance the structure of your resources Stick to the principle "not too flat and not too deep" with regard to the number of subfolders and the elements they contain for structuring your project resources. This leads to an optimized overview and facilitates access to certain substructures. Sample structures:

Unbalanced structure Well-balanced structure


2. Group resources Group resources with respect to their type (documents, sources, build results, ...) and their dependencies on each other. This optimizes SCM features such as resource locks, access rights, change notifications or partial check-outs. Automatic build or deployment scripts can also be developed more easily if you group semantically equal document types together. Sample structures:

Inefficient group structure Well-grouped structure

3. Use naming conventions Name all your folders or specific files in a standardized way so that the names are meaningful. This facilitates navigation and helps new developers to familiarize themselves with the structure. Using clear and unique naming conventions also facilitates the definition of "ignored resources" (resources which will be excluded from SCM version control), since their definition is based on wildcard filters.


Sample structures:

Structure without naming conventions Structure with naming conventions

4. Combine dependent modules within one project All modules and resources which follow the same project lifecycle, for example, if they are to be released together, should be part of one SCM project. This helps when defining releases and creating branches, and avoids inconsistent version numbering. If your development environment does not support multiple projects within one structure (e.g. Eclipse Java Development), you may use the partial check out mechanism to work on single modules. Sample project:


2.2 Migrating Large Projects Projects containing thousands of resources (files and folders) and having deeply nested, huge folder structures are referred to as "large projects". The size of a project also depends on the total size of its content.

Be aware of the following:

All write actions of SCM are invoked under full Enabler transaction control. This means that in case of an error, all changes written until the error occurred are rolled back.

• Transaction timeout The transaction mechanism of Enabler defines a so-called transaction timeout. After a defined period of time, a transaction will automatically be aborted and all changes made during the transaction up to this point will be rolled back. This feature is required for detecting broken connections from clients. Although SCM has a built-in feature to control and adjust the transaction timeout period, large project structures with big files may lead to a timeout.

• Number of operations within transactions Every operation invoked within an Enabler transaction requires some amount of space on the Enabler server. This amount can differ for each Enabler repository. If the space required by the number of invoked actions exceeds the defined amount, the repository will safely shut down - and the transaction will be aborted.

You can circumvent the above situations by changing the repository settings:

The Enabler repository parameters can be adjusted to allow for large, long-lasting transactions. Be aware, however, of the following: Changing the repository default values might decrease the performance of the Enabler system and might allocate unnecessary disk space.

The Enabler repository parameters can be modified using the Enabler Administration tool. When using an Enabler release prior to 7.0, you must stop the repository before you can change a parameter. The following repository parameters are relevant for importing large projects into SCM:

Recovery log file size

The recovery log file size specifies how big the recovery log file may become. In Enabler releases prior to 7.0, the number of operations allowed within a transaction is limited by the recovery log file size. If the file is too small to record all operations in a transaction, the transaction is rolled back. You may reduce the value for the maximum size of the recovery log file only after having made a backup or save of the repository.

Range (recovery buffer pages of 8 KB in size)

Enabler 6.2: between 500 – 2GB

Enabler 7.0: between 500 – 2GB, but transactions can be spread across an unlimited number of files

SCM Default (before 2.1): 10.000 (corresponds to a maximum file size of 80 MB)

SCM Default (since 2.1): 100.000 (corresponds to a maximum file size of 800 MB)


Maximum number of locks

Locks on objects and relationships can be set explicitly by tools or implicitly by transactions. The maximum number of locks that have to be configured for a repository depends on the following: number of transactions that can be executed simultaneously, number of users simultaneously accessing the repository, and whether locks are used by the tools that work on the repository.

Increasing the setting for the number of locks slightly increases the space required by the repository processes in memory.

Range

Enabler 6.2 < fix 6: between 500 and 200,000

Enabler 6.2 >= fix 6: between 500 and 1.5 Mio

Enabler >= 7.0 SP1: between 500 and 20 Mio

SCM Default: 50.000

Recommended settings

The following table summarizes the recommended Enabler repository settings:

Project size Recommended values

Number of files Number of folders Number of locks Recovery log file size

500 150 5,000 6,000

1,000 300 30,000 10,000

3,000 1,000 40,000 50,000

10,000 2,500 50,000 80,000

20,000 3,000 100,000 100,000

30,000 4,000 200,000 150,000

> 40,000 > 5,000 200,000 250,000

Default SCM settings: 50,000 100,000


2.3 Preparing the SCM Environment Before you start with the migration of a project, make sure that you have installed the SCM environment correctly.

This includes the following steps:

1. Install the SCM client interface on all clients of the project team. For details. refer to the Interstage ADM Installation Instructions.

2. Set up an SCM repository. For details, refer to the Interstage ASM Administration Guide.

3. Make sure that the file system allows to store the folder / file structure of the source project history with regard to maximum folder depth, maximum path length and name.

4. Define a user group within your company domain, which contains all project members. By default, this group has full access to all project resources. The group must be known to the host on which the SCM repository is running.

5. Make sure that source project files or directories with names of language specific characters can be created on the target file system. Check whether you need to install support for the particular language on the operating systems used for migration.

2.4 Creating a Backup Before you migrate your project resources to SCM, make sure that you have a backup of all existing project resources. Always copy the resources to be migrated into a temporary folder. After successful migration, this folder can be deleted.

Never migrate a productive file store directly!


3 Automated Migration SCM allows for an automated migration of project histories from other software configuration management systems to SCM.

Currently, automated migration of CVS and VSS projects is supported. Automated CVS migration is provided as a separate Eclipse plug-in, VSS migration as a command line tool.

In general, automated migration is performed in two separate steps:

• Step 1: Exporting The content of a software configuration management folder with all existing and deleted file versions is exported to the file system. How this step is performed, depends on the software configuration management system from which you are exporting. Section 3.3, Automatically Migrating CVS Projects, describes the procedure for CVS projects. Section 3.4, Automatically Migrating VSS Projects, describes the procedure for VSS projects.

• Step 2: Importing A new SCM project is created, and the project structure exported to the file system in Step 1 is imported. This step is irrespective of the software configuration management system from which you are migrating to SCM. Section 3.5, Importing into SCM, describes the procedure.

3.1 Migration in steps In case of huge project structures, especially when many configurations are to be migrated, the complete migration can take several hours or even days. Therefore SCM allows migrating CVS projects in several steps in the following way. In the first steps all resources, versions and configurations are migrated, which are read-only. These steps can be repeated, while the work on the project can continue. Just for the final step, when all the writeable resources, versions and configurations are migrated, the work on the project should be interrupted.

As with each repeated migration just the remaining delta is migrated, the execution time for each step is accordingly shorter. The sections 3.3.6 and 3.5.4 describe how to use this feature. For the export this feature is currently not supported for VSS projects.

3.2 Preparations Before you can use the automated migration facility, several preparation steps are required. Depending on the software configuration management system from which you are migrating, additional steps might be required.



3.2.1

3.2.2

System Requirements Make sure that you can meet the following requirements:

• Read Chapter 2, "Before the Migration".

• Repository Enabler 6.2 Fix 4 or higher is required to be installed on the system running the SCM target repository. Use SCM to create the SCM target repository on the target system. For details on how to create a repository, refer to the Interstage ASM Administration Guide.

• User credentials You need the user name and password of the administrator of the project that is to be migrated.

• File System The target system must be capable to store the exported folder and file versions with their complete path. Note: For Windows file systems the allowed path length is limited to 260 bytes, path and file names are case-insensitive. If the source repository contains resources with long path names or names differing only in their case spelling, an operating system should be chosen instead whose file system can handle these cases, i.e. UNIX/Linux. The export fails or the structure cannot be imported if an exported resource exceeds the file system limit. The export path for a file or a folder version stored under the export destination directory has the following format: <EXPORT PATH>/RES/<VERSION PATH>/<VERSION IDENTIFIER>.zip

EXPORT PATH – The path of the chosen export directory VERSION PATH – Full project relative path of the first version with name and extension VERSION IDENTIFIER – An identifier starting with "E_" for existing or "D_" for deleted versions followed by the SCM version number.

Creating a Target Directory Create a target directory to which the project will be exported. The target system must be capable to store the exported folder and file versions with their complete path. Therefore, choose a short path for the export destination. Consider especially the path length limitation, if Windows is used (see Section 3.2.1, System Requirements).

If the repository contains resources using language-specific characters, the corresponding language support must be installed on the target system.


3.2.3

3.2.4

Providing Sufficient Disk Space Exported resources are stored in a compressed format on the target system. Ensure that there is enough disk space on the target system for storing the project history with the content of all file versions. Depending on the number of binary files in the project, the required size is approximately equal to the size of the corresponding module folder in the repository of the "foreign" software configuration management system, e.g. CVS.

The required disk space is calculated as follows:

Number of files * average number of versions per file * average version size + ~10%

Preparing the Command Line Interface Usage For automatically exporting and importing project structures into SCM, you need to use the Interstage ASM command line interface. Set the following environment variables for the command line interface:

• PATH Optionally, for convenience reasons, the PATH variable can be augmented with the directory where the start script resides, i.e. the commandline subdirectory of the Interstage ASM installation directory.

• ASM_VMARGS

Options for the Java runtime environment can be set in this variable. The command line interface calls the java executable with these options in the following way:

Windows: %JAVA_HOME%\bin\java %ASM_VMARGS%

UNIX/Linux: $JAVA_HOME/bin/java $ASM_VMARGS

The command line interface is used to export and import the project to the target directory on the file system.

For details on installing the command line interface, refer to the Interstage ADM Command Line Interface manual.

Windows

For an overview of available commands, type

{escmmigration | escmvssmigration} --help

on the Windows command line.

For instructions on a particular command, execute

{escmmigration | escmvssmigration} --help <command>


UNIX/Linux

For an overview of available commands, type

escmmigration.sh --help

in the command shell.

For instructions on a particular command, execute

escmmigration.sh --help <command>

All migration commands are described in Appendix C, Migration Commands.

3.2.5 Considering Memory Requirements Exporting and importing huge projects might require more memory than is typically available. Increase the memory of the Java Virtual Machine to 512 MB.

To set the heap size of the JVM for exporting a project from a software configuration management system, edit the start command of Eclipse and insert the JVM parameters, for example:

eclipse.exe -vmargs –Xmx512M

For command line execution, you can define the JVM parameters in the ASM_VMARGS environment variable (see Section 3.2.4, Preparing the Command Line Interface Usage), for example by executing the following command:

set ASM_VMARGS=–Xms512m –Xmx512m

3.2.6

3.2.7

Considering the Duration of a Migration Exporting and importing project resources are long running actions. The whole migration can take several hours depending on the size of the repository. Ensure that the repository server is up and running during the whole migration process. It is common practice to stop repository servers in enterprise environments for night-shift reorganization or server backups.

In addition, file system access performance can be enhanced by disabling virus shields and scanners on the target system folders to which resources are exported.

Logging SCM writes a lot of logging information during the export as well as during the import process. The following log files are created.

Migration log file

For each version which has been exported or imported, an entry is written in a trace.log file which is stored in the specified directory.


Example entry for an exported version:

[26.09.2007 17:39:09] -->1.1 -->Test.java[1]

The entry contains the date, the number of the original version and the name of the item in SCM.

Using this file, the user can trace every object which has been processed by the migration. This file also provides detailed information in case of errors.

Environment log files

SCM also logs detailed information about the used environment. The file ExportEnv.xml is created during the export. It contains the location and application details of the migration source, the used application versions and the system properties which were set on the host where the export was executed.

The file ImportEnv.xml is created during the import. It contains the location information on the migration target, the used application version and the system properties which were set on the host where the import was executed.

For details about the XML syntax of the log files, refer to Appendix B, Environment XML Files.

3.2.8

3.2.9

Commit comments SCM can store commit comments of up to 512 bytes. The export process results in a warning for each version, which does not have a commit comment or whose comment might exceed the maximum size of 512 bytes in worst case. The actual needed size of a commit comment depends on the used encoding. The export calculates the maximum needed size for each comment, considering that the user name and the original identification number (CVS: revision) of the version could be appended if they differ. For details, refer to Section 3.5.3, Handling comments.

Copying the exported structure If you copy the exported structure from one place to the other, be sure to copy all contained files and folders. The exported structure might contain files and folders, which are ignored by some tools. For instance the built-in ZIP function of Windows ignores folders whose names start with a dot (“.”). Therefore check the number of files and folders of the exported root folder before and after copying or compressing and decompressing them.


3.2.10 Restrictions Since there are structural differences between SCM repositories and other repositories, some limitations apply for the automated migration:

• Users and groups Users and groups in a software configuration management system are, in most cases, unknown to the target SCM repository, or differ in their name spelling. Since the user and group concept of SCM and other systems may differ, users and groups cannot be migrated automatically. In addition, version histories can contain names of users that no longer exist. This is not supported by SCM histories. In order to migrate users, you need to create a mapping after exporting the project. SCM provides a command to extract the users from the exported project, and create a default mapping, which can be edited. For details, refer to Section 3.5.2, Creating the User Mapping .

• Access rights Access rights applied in other software configuration management systems cannot be migrated automatically. They must be defined manually after importing the project into SCM. For details, refer to Section 5.1, Setting up Roles and Authorities.

• Locks SCM provides mechanisms to lock resources or whole configurations in the repository for providing exclusive write access. This information cannot be migrated.

3.3 Automatically Migrating CVS Projects SCM allows for an automated migration of CVS projects and their histories to SCM. This functionality is provided as a separate Eclipse plug-in: the CVS Migration plug-in of SCM.

Using this plug-in, you can migrate the complete version history of CVS projects to SCM. This includes the migration of all files and folders, and versions of the project stored in the repository.

This section describes how to export the content of a CVS repository folder with all existing and deleted file versions to the file system. Importing the exported project structure into SCM is independent of the software management system from which it has been exported.

Note: SCM and CVS are using different default mechanisms to assign the date and time to resources when checking out or updating them. In CVS, the behavior is not consistent. For update operations CVS assigns the current date and time of the operation, for override & update as well as check-out operations it assigns the last modification date and time stored in the repository. SCM assigns the last modification date and time which is stored in the repository to all checked out or updated resources by default, but allows you to change this setting to the current date of the operation. For details, refer to the Interstage ADM Command Line Interface manual and the Interstage ADM Software Configuration Management User Guide (online help).


The following steps are involved in performing a complete migration from CVS to SCM:

1. Preparations (see Section 3.3.1) – For best results, it is recommended to optimize the project structure before the migration (see Chapter 2). Verify that the migration environment meets the system requirements, e.g. sufficient disk space and memory (see Section 3.2). For details on restrictions that might apply to the planned CVS migration, refer to Section 3.3.7.

2. Defining the Project Mapping (see Section 3.3.3) – In order to create an SCM structure which matches the CVS project structure, it is necessary to define the hierarchy of configurations and releases. This is done in the project mapping.

3. Running the Exporter (see Section 3.3.4) – In this step the content of a CVS repository folder with all existing and deleted file versions is exported to the file system.

4. Defining the User Mapping (see Section 3.5.2) – The user mapping defines how CVS users are mapped to SCM users.

5. Importing into SCM (see Section 3.5) – In this step, the exported project structure is imported from the file system into SCM.

6. Finishing Up (see Chapter 5) – In this final step, necessary adjustments of SCM settings not covered by the automated migration are performed.

3.3.1 Preparations The automatic migration of CVS projects requires Eclipse 3.2 or higher. The following additional Eclipse plug-in needs to be installed:

• com.fujitsu.enabler.eclipse.scm.cvsexport_# for accessing the repository. The CVS server must be compatible with the Eclipse plug-in. At least all resources of the project must be browseable and the version history of all files must be accessible from the CVS repository view. For information about compatibility, refer to the Web sites CVS FAQ and CVS Compatibility.

In addition, make sure that your Eclipse installation comprises the following default Eclipse plug-ins:

• org.eclipse.team.cvs.core_#

• org.eclipse.team.cvs.ui_#

Proceed as follows to export the content of a CVS project:

1. Connect to CVS: Select Windows > Show View > Other > CVS > CVS Repositories from the Eclipse menu.

http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-vcm-home/docs/online/cvs_features2.0/cvs-faq.html

http://dev.eclipse.org/viewcvs/index.cgi/platform-vcm-home/docs/online/html-cvs/cvs-compatibility.html?rev=1.4

Right-click in the CVS Repositories view, and select New > Repository Location from the context menu.

Enter the location data and the user credentials for the CVS repository whose projects you want to migrate. Click Finish to connect to the CVS system.


2. Specify the server encoding In CVS it must be specified, which encoding is used for accessing the repository. This is a common agreement of the users who use this repository. This encoding must be set in the preference page of the CVS location before exporting. Therefore select the created CVS connection in the CVS Repositories view, click the right mouse button and choose Properties from the context menu. Select the tab Server Encoding and chose the encoding setting.


3. Check the structure: To view all versions that can be migrated, open the folder named Versions in the Repository view, and expand the module you want to migrate. If versions of the project to be migrated are missing in the tree view, you must add the relevant tags manually: Right-click the relevant module and select Configure Branch and Versions from the context menu. For detailed instructions on how to add tags, refer to the section “Discovering Branches and Version tags” in the CVS online help.

4. Open the SCM Export wizard:

In Eclipse, open the CVS Repositories view and connect to the server holding the CVS module to be migrated. To export the CVS module without its current state (HEAD), right-click the module folder under Versions, and select Export Project to SCM from the context menu.


To export the CVS module including its current state (HEAD), right-click the folder of the project to be migrated and HEAD, and select Export Project to SCM from the context menu.

The SCM Export wizard appears. This wizard leads you through the export process.

5. Define the export target. For details, refer to Section 3.3.2, Defining the Export Target.

6. Define the SCM project structure. For details, refer to section 3.3.3, Defining the SCM Project Structure.

7. Start the export. For details, refer to section 3.3.4, Starting the Export.



3.3.2 Defining the Export Target In the first dialog of the SCM Export wizard, you specify the export target.

1. In the Project Name field, enter a name that will be used as SCM project name. By default, the project name is the name of the folder or module you selected.

2. In the Export Directory field, specify the directory to which the content of the CVS folder/module will be exported. Clicking Select allows you to browse your file system. Note: Choose a short path name so that all versions with their full path length can be written to the export directory. Be aware of path length limitations of the file system.

3. Decide whether you want to use a mapping file. You can define an XML mapping file that defines how the CVS project is mapped to SCM entities. For details about the syntax of the XML, refer to Appendix A, Migration Mapping File. For using a custom mapping file, select the Use mapping file checkbox, and specify the full path and name of the file. Click Select to browse your file system for it. If you do not specify a mapping file, a default mapping is created: The HEAD branch and all CVS version labels in this mapping (sorted in descending alphabetical order) are mapped to SCM configurations with the same name. All configurations become members of an SCM release named "1.0".

4. Click Next to view and edit the mappings. Refer to the next section for details.


3.3.3 Defining the SCM Project Structure SCM provides a hierarchical project structure. This structure can consist of releases, branch releases, branch configurations and snapshots. CVS projects do not define such a hierarchy. They contain labels of branches and versions that reference analogous compound structures.

In order to create an SCM structure that matches the CVS project structure, you can define the hierarchy of configurations and releases, and name them as desired.

The second dialog of the SCM Export wizard displays the mapping of CVS labels to SCM configurations, for example:

The first column (Name) in the table defines the labels of CVS version tags or branches. All other columns (Target Name, Release, Type, Open, Predecessor) refer to the SCM entity.

Proceed as follows to define the SCM project structure:

1. Select the CVS modules to be exported. Select the labels of version tags or branches to be exported by clicking the relevant checkboxes.

2. Define the SCM configurations and releases.

SCM configurations and releases (type) are defined by their name, their open state, their predecessor and the name of the release they belong too. a) Renaming a configuration You can rename the configurations and releases as desired. The new name must

be unique within a release. Select the relevant row in the table, click in the Target Name column, enter a new name, and click Change Name.

b) Defining the Open state The Open state defines whether a configuration is a snapshot or a branch. A

snapshot is closed and write protected, a branch is open and allows that resources are committed to it.

To change the state, click the Open column, and change the value. If you set the Open state to Yes for a configuration, make sure that this configuration has no successors: There must be no entry in the Predecessor column.

c) Renaming a release To rename a release, select the configuration which will be the first configuration

in this release. The first configuration of a release is the one whose predecessor value (the Predecessor column) is either empty or refers to a configuration with a different release name. For release "1.0", in the default mapping, this is the configuration in last table row.

To rename a release, click the Release column, and enter a new value. Note: The name of the release must be unique for the project. An error will be

displayed when the release definition is not unique. In this case, choose a different release name or change the predecessor.

d) Defining new releases You can define new releases by renaming the release name of the first

configuration: Select the first configuration of the release, then click the Release column, and enter a new value.

All successors of the configuration within the renamed release become members of the new release.

e) Defining the sequence and hierarchy The hierarchy of the structure is defined by the predecessor of each

configuration. To change the order of a configuration in the structure, select the Predecessor field and choose a value from the list. Because the defined configuration structure must be hierarchical (a tree), only those predecessor configurations are available for selection, which do not create circles. The structure must have one first configuration. This is indicated by the empty "Predecessor" field. Click Sort list to resort after changing a predecessor.

f) Changing the release type To change the release type, select the first configuration of a release and click on

the value displayed in the Type column. The release type can either be a follow-up release (simply named "Release") or a branch release. For a release, only one release can be defined as follow-up release. If a different release is already defined as the follow-up for the release, only the type "Branch Release" is available.



3.3.4 Starting the Export To start the export of the CVS project, click Finish. During the export process, the currently processed versions are written to a trace file located in the chosen export folder and logged to the console. The currently processed directory is also shown in the status bar.

3.3.5

3.3.6

Resuming an Aborted Export If you click Cancel or if an error occurs, the export will abort with a corresponding message. All exported files and folders will remain in the export directory. You can resume the export by repeating the above listed steps. In this case the configurations and versions already exported will be skipped. Even though the already exported resources are skipped when resuming the export, it can still take some time until the resuming position is reached. This is because the iteration over the repository takes some time.

Do not modify the exported structure or the source project if it is not completely exported when resuming the export process.

Multiple Export In case of huge projects - especially when many labels have to be migrated - the total migration can take several hours or days. But in common cases it is required, that the work on the project does not stop for a longer time. Therefore SCM allows to migrate huge projects in several steps.

Using the option “Multiple Export” the export can be executed several times and each time the user can specify additional labels which will be migrated. This allows to migrate a project in the following way:

- First all labels of tags are migrated. These are read-only. They will be migrated as snapshot and cannot change during the ongoing development.

- In later steps, remaining or newly created labels are migrated.

- In a final step all branches are migrated. Just for this step it is required that the work on the project is stopped.


When selecting “Multiple Export”, SCM will create all information, which is needed to repeat the export and to skip all resources and configurations that have already been processed. When importing the structure after each export run the import command must be called with the option –multi. For details about importing projects, refer to Section 3.5.3, Handling comments.

For exporting the first set of labels, proceed in the same way as described in 3.3.2., but select the option Multiple Export. It is recommended to import the mapping for these labels from an XML file. For details on the syntax, refer to Appendix A, Migration Mapping File.

If you want to repeat an export for migrating additional labels, call the export again from the context menu of the same folder in the CVS Repository view. Ensure that the same project name and target directory are selected in the Export Target wizard page. Create and edit a copy of the mapping.xml file, which has been created by the previous export run in the specified export directory. Add remaining labels, which you want to migrate in this run and import this file copy. Select the option Multiple Export and press Next and Finish.

For the final export, proceed in the same way as before but deselect the option Multiple Export. Finally, select additionally the braches which should be migrated, or add them to the imported mapping file and re-execute the export.

3.3.7 Restrictions Since there are structural differences between SCM repositories and CVS repositories and limitations of the CVS client, the following restrictions apply for the automated migration of CVS projects:

- Labeled substructures

SCM migrates CVS modules with the head and all selected version tags to SCM configurations. If, in the CVS project, subfolders of a module are tagged, these tags can be migrated as well; however, this might have an impact on the SCM change reports, especially source code statistics.

From the SCM point of view, the created SCM configurations are to some extent incomplete: The SCM compare and change report functions might consider resources as deleted or added, which is incorrect.

- Modification times

Because of a limitation of the Eclipse CVS API, the last modification time of file resources cannot be migrated.

- Modification of migrated labels

This applies to the multiple migration. Using this feature the working on the source project can continue during the migration process. But configurations (labels, branches) which have been migrated must neither be deleted nor modified (for example by tagging additional resources with an existing label).


3.4 Automatically Migrating VSS Projects SCM allows for an automated migration of VSS projects and their histories to SCM. This functionality is provided as a command line tool: the VSS exporter of SCM.

Using this command line tool, you can migrate the complete version history of projects maintained in VSS to SCM. This includes the migration of all files and folders, and versions of the project stored in the repository.

This section describes how to export projects from VSS with all existing and deleted file versions to the file system. Importing the exported project structure into SCM is independent of the software management system from which it has been exported.

The following steps are involved in performing a complete migration from VSS to SCM:

1. Preparations (see Section 3.4.1) – For best results, it is recommended to optimize the project structure before the migration (see Chapter 2). Verify that the migration environment meets the system requirements, e.g. sufficient disk space and memory, and that the command line tool is properly installed (see Section 3.2). For details on restrictions that might apply to the planned VSS migration, refer to Section 3.4.6.

2. Defining the Project Mapping (see Section 3.4.2) – The project mapping defines which VSS projects contain which releases, and which labels on these VSS projects represent configurations.

3. Running the Exporter (see Section 3.4.3) – In this step, all existing and deleted file version are exported to the file system.

4. Defining the User Mapping (see Section 3.5.2) – The user mapping defines how VSS users are mapped to SCM users.

5. Importing into SCM (see Section 3.5) – In this step, the exported project structure is imported from the file system into SCM.

6. Finishing Up (see Chapter 5) – In this final step, necessary adjustments of SCM settings that are not covered by the automated migration are performed.

3.4.1 Preparations Requirements

In addition to the requirements described in Section 3.2.1, the following requirements have to be met:

• Microsoft Visual SourceSafe 6.0c installed. Currently supported language versions of VSS are English, German, and Japanese.

VSS Database Format

The VSS database needs to be in the format of Visual SourceSafe 6.0. For databases in older formats, there is an update tool included in VSS 6.0. Before exporting, check your database format, and if necessary, run this tool to upgrade your database to the VSS 6.0 format. For details, check the VSS documentation for DDUPD in the section VSS Utilities.

Project Mapping

A mapping for the releases and configurations that should be exported has to be created. The next section covers this in more detail.


3.4.2 Defining the Project Mapping Before a project can be exported from VSS, an appropriate project mapping in the form of an XML file has to be created. The project mapping defines which VSS projects contain which releases, and which labels on these VSS projects represent configurations. The following section describes the general format for project mappings in the SCM migration framework. For details about the syntax of this XML file, refer to Appendix A. Migration Mapping File.

Note: The term VSS project does not refer to a project as used in SCM. VSS does not support projects. In VSS terminology, any resource folder is called a project. When the term VSS project is used in this chapter, it is used to convey this meaning.

The concepts of releases and configurations, as enforced by SCM, do not exist as such in VSS. In order to migrate resources from VSS to SCM, the VSS exporter makes certain assumptions about the way in which resources are organized in the VSS database.

Releases and Configurations

• Release - A release is understood to be a certain VSS project.

Restriction: A VSS project that represents a release must not reside inside a sub-tree rooted in another VSS project that also represents a release.

• Configuration - A configuration is understood to be a certain version of a certain VSS project, optionally marked by a label on that project.

Consider the following example:

The project MyProject has two releases, one maintained in the folder MyProject_1.0, and one in MyProject_2.0. Therefore, the contents of folder MyProject_1.0 constitutes release 1.0 of MyProject, the contents of MyProject_2.0 release 2.0. Any labels on these two folders can be used to further define configurations within each release.

Only resources structured in this fashion can be properly mapped to releases and configurations in SCM. To illustrate the restriction in the above definition of a release, consider the following case: If the folder MyProject_2.0 of the above example resides in MyProject_1.0, the resources cannot be separated into two distinct releases.

The project mapping XML file for this example could look as follows (assuming that the labels L1 and L2 are defined in both releases, and release 2 was branched off L1 in release 1):

<?xml version="1.1" encoding="UTF-8"?>

<migrationmapping>

<project name="MyProject">

<configuration escmname="L1" id="R1_L1" label="$/MyProject1.0$L1"

open="false" release="R1" state="archived" type="release"/>


open="false" predecessor="R1_L1" release="R1"

state="archived" type="configuration"/>

<configuration escmname="MAIN" id="R1_MAIN"

label="$/MyProject1.0$" open="true" predecessor="R1_L2"

release="R1" state="in development" type="configuration"/>



state="archived" type="release"/>



state="archived" type="configuration"/>

<configuration escmname="MAIN" id="R2_MAIN"

label="$/MyProject2.0$" open="true" predecessor="R2_L2" release="R2"

state="in development" type="configuration"/>

<release name="R1"/>

<release name="R2"/>

</project>

</migrationmapping>

Note the way in which a configuration is specified in the label field. This is different from the format defined in Appendix A, Migration Mapping File. It is the full path (in VSS terms: spec) of the VSS project holding the release, followed by $label, the label corresponding to the configuration within that release:

$/<release path>$<label>

E.g.:

label="$/MyProject1.0$L1"

for configuration L1 in release 1. The MAIN configuration is specified by only providing the release spec, followed by a $ sign. e.g.:

label="$/MyProject2.0$"

for the MAIN configuration of release 2.

Resources

Resources are exported with all of their versions. Renames of resources are considered during the export. Resources that are deleted in the current configuration of a release will still be completely exported if at least one configuration in which this resource is not deleted is referenced in the project mapping. Otherwise the resource is not exported.


Links

VSS allows resources to be linked. This concept is not supported in SCM. During an export, links are treated in the following way:

• Given a set of linked resources, all resources in that set that share the same relative paths in all versions are exported as one resource. Those resources that share their relative path with no other resource in the set, are exported as independent resources. In all cases, resource versions and history information are fully retained.

The relative path of a resource is the path to the resource, starting from the VSS project that represents the release to which the resource belongs.

Consider the following example:

The resource res/autorun.gif was created in release 1.0 of MyProject, and then linked into release 2.0. In both releases, the relative path is res. autorun.gif, and is therefore exported as one resource. When imported into SCM, both releases will use the same resource autorun.gif. If autorun.gif is additionally linked to a location with a different relative path, e.g. src in release 2.0, then this location will receive its own identical, but separate resource autorun.gif.

An implication of the above is that links within the same release are discarded. Links to locations that are outside of the migration scope – i.e. locations that are not contained in any of the VSS projects referenced as releases in the project mapping – are also discarded.

Note that during the export branches are treated with higher priority than links. For details, refer to the section Branches.


Branches

During an export, resource branches are retained. However, while SCM uses branches in a strict SCM sense, branches in VSS are also commonly used to copy and move resources. This may cause problems that lead to the following restrictions:

• During the life of a project in VSS, resources may be repeatedly branched in order to move them to different locations. This can lead to cyclic branch structures. If a branch cycle is detected during the export of a resource, only the branch structure up to the point before it closes the first cycle is exported. The remaining branch relationships are discarded. Note that this does not mean that the resources at the locations of these branches are discarded, but only that the branch relationship is ignored.

An example: The resource A is first created in folder a, then branched into b, from there into c, and then from c back into a. Finally it is branched from a in to d. The export detects the cycle a-b-c-a, and accordingly only exports the branch relationships a-b-c. The resource A in folder d will, however, still be exported, but as a separate resource that is not connected to the resource from the folders a, b, and c.

• Repeated branching to move a resource can also lead to a situation where a location in the branch structure does no longer exist. To use the previous example, after branching resource A from folder b into c, folder b may be deleted. In this case, the export will try to re-connect the branch with an earlier branch base that still exists. In the example, resource A in folder c would be connected through a branch relationship with resource A in folder a, skipping the no longer existing location b. If all branch bases are deleted, the resource is treated as an independent resource with no branch relationships. (Further branches starting from this resource however will be considered.)

Further restrictions:

• A branch relationship between two resources is discarded if the two resources do not have the same relative paths from version 1 up to the version at which the branch occurred.

• Branches to locations that are outside of the migration scope are discarded, i.e. locations that are not contained in any of the release VSS projects referenced in the project mapping.

• When a resource involved in a branch is linked in addition, this link relationship is discarded. Note that the resource at the other end of the link is retained and exported as a separate resource.

• If all resources involved in a branch are deleted, information about the branch relationships can no longer be retrieved from VSS. The resources are treated as independent in this case.


Version Comments

Comments for versions are migrated in the following format:

[<action>](<original version number>) <comment> <label comment>

The meanings of the fields are:

• action – The VSS action that created the version.

• original version number – The version number assigned to this version by VSS. The export may assign a different number (see Export Version Numbers).

• comment – The original comment for the version.

• label comment - If the version was created through a label, this is the comment of the label. For all other types of versions, this is omitted.

For example:

[Checked in](12) Fix for bug #236217

Export Version Numbers

Mostly, resources keep their original version number as assigned in VSS. In the following cases however, version numbers for a resource will be different after import into SCM:

• The resource or any of its parent folders was renamed.

VSS does not create a new version when a resource is renamed. Instead the parent entity of that resource receives a new version. This behavior conflicts with SCM. The exporter therefore inserts an additional version for each rename.

• The resource is involved in a branch.

VSS always manages version numbers separately for each resource, even if it is a branched resource. To create a proper version tree in SCM for branched resources, new version numbers are assigned chronologically to all involved versions.

The original version number is always included in the version comment (see Version Comments).

User Access Rights

User access rights can be included in the export. The four access right levels defined in VSS are translated to the levels in SCM in the following way:

VSS SCM READ READ CHECK OUT WRITE ADD WRITE DESTROY WRITE



Note, however, that SCM only allows a maximum of 8 explicit access right settings per resource. The VSS exporter discards any additional access right information and logs a warning. It is advisable to manage user access rights after migration using the role and user administration features of SCM.

3.4.3 Starting the Export The VSS exporter should be run on the same machine that hosts the VSS database. While remote access to a VSS database is generally possible via a network share, the use of this method is discouraged due to its severe performance impediment.

Prerequisites

Before starting the exporter, verify the following prerequisites:

SSAPI.DLL

The exporter relies on the SSAPI.DLL of VSS. If this DLL is not correctly registered during the installation of VSS, the exporter will abort with the following error message:

800401f3: Invalid class string

In this case, SSAPI.DLL must be registered manually. To do so, open a DOS prompt and execute the following command:

regsvr32.exe "<full path of SSAPI.DLL>"

A dialog should be displayed confirming the registration of the DLL.

Path to VSS

Additionally, it is necessary to add the path to the SS.EXE, the VSS command line, to the PATH environment variable of Windows.

Example:

To export the VSS project MyProject to the D:\migration folder and create the project mapping file D:\docs\MyProject.xml, execute:

escmvssmigration export -p MyProject -v D:\vss -u user1 -t D:\migration -m D:\docs\MyProject.xml

For details on the command syntax, refer to Appendix C, Migration Commands.


3.4.4

3.4.5

3.4.6

Error Handling VSS suffers from a series of flaws and bugs. Additionally, VSS repositories easily become inconsistent or even corrupted during productive use. This makes error free exporting rather difficult, if not impossible. In order to keep an export running even in the event of an error, the following fall back solutions for commonly observed problems are used:

• If the contents of a given resource version can be retrieved, but not connected to its version history, this resource version is exported with a dummy history. This history contains only one version representing the recovery of the resource version. In this way, the contents of the particular resource version are not lost, only disconnected from its actual history. A corresponding warning is logged.

• If the contents of a given resource version cannot be retrieved, a dummy file with the name of the resource version is exported instead. It contains a note that the contents of the resource version could not be retrieved. In this way, the user of the migrated project at least will know that the resource existed, and can take measures to manually restore it, if possible. A corresponding warning is also logged.

If the exporter cannot handle a version resource at all, it is not exported and instead added to a “black list” of failed items. The list is named FailedItems.xml and can be found in the export target folder. After an export this list should be checked, and all resource versions contained in it should be investigated and migrated manually, if necessary.

Resuming an Aborted Export If you stop the export or an error occurs, the export will abort with a corresponding message. All exported files and folders will remain in the export directory. You can resume the export by repeating the steps listed above. In this case the configurations already exported and versions will be skipped. Even though the resources already exported are skipped when resuming the export, it can still take some time until the resuming position is reached. This is because the iteration over the repository takes some time.

Do not modify the exported structure or the source project if it is not completely exported when resuming the export process.

Restrictions The following is a list of restrictions. Some of the items are covered in more detail in the previous sections. Where applicable, a reference is given.

• Releases: A VSS Project that represents a release must not reside inside a sub-tree rooted in another VSS project that also represents a release (see Releases and Configurations).

• Links: Only links between resources with the same relative path are considered (see Links).

• Links & Branches: Branches are treated with higher priority than links (see Branches).

• Branches: Cyclic branch structures are discarded, deleted branch locations skipped, resources in completely deleted branches treated as separate (see Branches).


• Version Numbers: Original version numbers are not always retained (see Export Version Numbers).

• Pinning: Not supported.

• Deleted resources: Resources that are not referenced by any of the configurations in the project mapping are not exported.

3.5 Importing into SCM The import of a project structure from the file system into SCM is independent of the software configuration management system from which the project has been exported.

The SCM command line is used to import a project exported to the file system into the target SCM repository. SCM must have been configured for command line execution. Refer to Section 3.2.4, Preparing the Command Line Interface Usage.

Note: If the target system to where the project should be migrated is not inside the same LAN, copy the exported project to the target host. Use FTP or write the exported project on external media (i.e. DVD or tapes) and copy it onto the target system. Refer to Section for 3.2.9, Copying the exported structure, for notes on copying the exported structure.

Importing the project into SCM requires the following steps to be performed:

• You need to define the users for the SCM project. For details, refer to Section 3.5.2, Creating the User Mapping.

• Import the files and folders as SCM project. For details, refer to Section 3.5.4, Importing the Project.

3.5.1

3.5.2

Multiple Import As mentioned in chapter 3.1, in case of huge project structures, especially when many configurations are to be migrated, the complete migration can take several hours or even days. Therefore project structures can be migrated in several steps by exporting and importing multiple times.

Creating the User Mapping Users and groups in a software configuration management system are, in most cases, unknown to the target SCM repository, or differ in their name spelling. Since the user and group concept of SCM and other systems may differ, users and groups cannot be migrated automatically. In addition, version histories of other systems can contain names of users that no longer exist. This is not supported by SCM histories.

SCM provides a command for generating a mapping file containing the names of all users appearing in the exported project history. This file is created in the root directory of the exported project.

Example:

To create a mapping of users that are contained in the project, which has been exported to C:\CVSProject, execute:

escmmigration usermapping C:\CVSProject



After generating this mapping, the corresponding user names of the target SCM repository must be inserted:

1. On the target host, create a default user mapping of project users. Use the command usermapping from the SCM command line.

2. Edit the created file users.xml in the specified target directory and insert the mapped (existing) users of the target repository.

<?xml version="1.0" encoding="UTF-8"?>

<users>

<user name="cvsuser1" newid="User"/>

<user name="cvsadmin" newid="Admin"/>

<user name="cvsuser2" newid="User"/>

<user name="cvstester" newid="Testuser"/>

<user name="cvsbuild" newid="Admin"/>

</users>

3.5.3 Handling comments When the mapped user names or the version numbers given by SCM are different from the exported version information, the original data will be appended to the commit comment of the relevant version, when the structure is imported. Optionally you can specify an option to suppress this modification of commit comments.

For information about the options of the import command, type:

escmmigration --help import

In any case the import process will automatically cut comments, which are longer than 512 bytes. Alternatively, you can choose to manually change or shorten the comments after the export. To do this, edit the version meta-file, versions.xml, of the relevant resource.

This file can be found under <EXPORT DESTINATION>/RES/<VERSION PATH>, where <VERSION PATH> is the path mentioned in the warning message shown in the export log file, trace.log. Ensure to take an appropriate text editor to preserve the encoding of the file content, when saving it. Change the value of the attribute ’comment’ of the relevant ‘entry’ tag matching the mentioned version.

3.5.4 Importing the Project After having created a user mapping file (see above), you finally import the project structure from the file system into SCM.

Prerequisites • The target SCM repository must be present, and the user name, group and password

of an administrator must be known.

• A mapping file of all users of the exported project must be stored in the root folder of the exported folder. For each user, this file must contain a corresponding name of a user that is known to the repository.

The import process can take some hours depending on the size of the project. When the import fails for some reasons – e.g. the connection was broken - it can be restarted by calling the same statement again. In this case, the files and folders already imported are skipped.

Don't modify the project if it is not completely imported when resuming the import process.

Using Multiple Import

As described in 3.1 the import and export of projects can be performed in several steps. To this end, the import command must be called with the option –multi. This will create all information which is needed for a subsequent import execution to import the added versions, resources and configuration (the delta). For the final import execution the command must be called without this option. This will finally seal the project.

Example:

The following command imports a project structure located in C:\CVSProject to the project "SCM Project" and retains resource information in the created project in order to import remaining parts in subsequent repeated executions.

escmmigration import –multi -ts localhost -td Enabler1 -tp "SCM Project" -g escmusers -u DOMAIN\Admin -pw admin C:\CVSProject



4 Manual Migration SCM allows you to migrate any project into an SCM repository, irrespective of whether the project has been managed by another source code management system. If you manually migrate a project, be aware that you need to MANUALLY migrate the project history, if available.

Note that SCM comes with a plug-in for automatically migrating CVS projects and a tool for VSS projects. For details, refer to Sections 3.3, Automatically Migrating CVS Projects, and 3.4, Automatically Migrating VSS Projects.

For all other software configuration management systems (e.g. RCS), you currently need to manually migrate them. You can, however, also choose to manually migrate CVS projects.

In general, manual migration is performed in several separate steps:

• Step 1: Exporting – Creating a base configuration In the current software configuration management system, you must define a configuration to be used as starting point for the development under SCM. The content of the base configuration with all file versions needs to be exported to the file system. For details, refer to Section 4.2, Defining a Base Configuration.

• Step 2: Creating a local Eclipse project out of the base configuration For details, refer to Section 4.3, Creating a Local Eclipse Project.

• Step 3: Importing the base configuration into SCM – creating an SCM project For details, refer to Section 4.4, Creating an SCM Project.

• Step 4: Defining an SCM release For details, refer to Section 4.5, Defining a Release.

4.1 Preparations Before you start with a manual migration, read Chapter 2, Before the Migration. In addition, observe the following:

• When you are migrating a large project, i.e. a project containing thousands of resources (files and folders) and having deeply nested, huge folder structures, be aware of the following: All write actions of SCM are invoked under full Enabler transaction control. This means that in case of an error, all changes written until the error occurred are rolled back. To avoid this, do not take a huge project structure under version control in one step. Divide the migration process into small, repetitive steps: When importing the base configuration, import one subfolder after another.


Sample: A project structure consists of 4000 resources. The source folder contains 2000 small resources, the document folder contains 1000 resources, and the binary folder contains 500 big files and 500 small files. After having created the SCM project, you can first take the source folder under version control. After the sources have been written to the repository, the corresponding transaction ends. Then you continue with taking the document folder under version control, followed by the binary folder containing big files, and finally followed by the binary folder containing small files. In this way, you manually split one big transaction into several small transactions. If an unexpected error occurs, for example, in case of a broken network connection, you need not repeat the whole migration, but can restart migration with the substructure that was processed when the error occurred.

• During the migration process, it might be required to change the project structure or to make modifications that might lead to an inconsistent structure. Apart from this, be aware that during the migration, all defined resources are treated like resources of a local workspace. As a consequence, new .escm files are created in each folder. These files hold meta information about the version history. They need to be removed before you import the project into SCM.

4.2 Defining a Base Configuration In your current software configuration management system, or on your file system, you must define a configuration to be used as starting point for the development under SCM. All resources contained in the base configuration will be created as version [1] in the SCM repository.

If you want to migrate more than one project version (e.g. previous or branch releases), you might want to rebuild the version history. You can do this directly in SCM. Refer to Section 4.6. Rebuilding the Version History.

Collecting All Developer Versions

Make sure that all developers integrate their current development versions into the structure of the project that is to be migrated to SCM.

When starting to use SCM, all developers need to check out the migrated working configuration once, i.e. the workspace used before the migration can either no longer be used or will be replaced by the SCM workspace.

If it is impossible to collect all current developer versions belonging to the project, synchronize mechanisms can be used for detecting local changes, and the latest changes from other team members can be integrated and the affected files be stored separately. The changes can be manually integrated after the check-out, for example by replacing the checked out resources with the stored files.

It is, however, recommended, to integrate all developer sources into one build, which is then used as the basis for the first SCM configuration. For example, when you release a project build, resources are no longer in development. This would be a good time for migrating to SCM.

The subsequent sections describe samples how to define a base configuration in CVS, RCS, and VSS.



4.2.1 CVS Base Configuration The following sample describes the necessary steps for defining the CVS base configuration. In the sample, a project called "Online Shop" is currently under CVS version control. The CVS repository looks as follows:

The latest development resources are labeled as "Rel_120_FINAL". This is to become the base configuration for SCM.

To export these resources, open a shell window and invoke:

cvs export -r Rel_120_FINAL -d "C:\tmp\Online Shop 1.20" "Online Shop"

This command exports the complete project structure of "Rel_120_FINAL" to the local folder C:\tmp\Online Shop 1.20.

This file structure can then be used for creating a local Eclipse project which can be imported into SCM. Refer to section 4.3, Creating a Local Eclipse Project.

4.2.2 RCS Base Configuration In RCS (Revision Control System), you need to check out all resources from the required revision in order to define a base configuration. Locking the resources is not required, since the resources are only required as input.

It is recommended to write a script which processes the whole project tree recursively and calls the following command on each file:

co -r120 filename

When the script has executed, the complete revision "120" is checked out.

Then copy the whole file structure to a temporary folder (e.g. C:\tmp\Online Shop 1.20) without the internal RCS folders (you may also delete them after the copy process).



4.2.3 VSS Base Configuration The following sample describes the necessary steps for defining the VSS (Visual Source Safe) base configuration. In the sample, a C++ project called "Online Shop" is currently under VSS version control. The VSS repository looks as follows:

The latest development resources are labeled "Rel_120_FINAL". This is to become the base configuration for SCM.

To export these resources, right-click the project node "Online Shop" and invoke Show History.

In the displayed dialog, a label-based view is defined, which will reveal all defined labels of the project:

After confirming the selection, "Release 1.20 FINAL" is selected in the next dialog and its content is copied to the local folder C:\tmp\Online Shop 1.20 by using the GET option.




4.2.4 Removing Administrative Resources During the migration process, it might be required to change the project structure or to make modifications that might lead to an inconsistent structure.

If your project structure contains resources from other software configuration management systems (like CVS), make sure to remove them completely since they are not required for SCM. SCM manages its own meta files. They are located under the project root folder in a folder named .escm. These files hold meta information about the version history.

4.3 Creating a Local Eclipse Project To migrate a project to SCM, its entire base configuration must be available as a local Eclipse project. For details on how to define a base configuration, refer to Section 4.2, Defining a Base Configuration.

In Eclipse, the project type will usually be "Simple". If the project includes only one module, you may also create a project of the underlying language type (e.g. "Java"). With regard to setting up a well-grouped project structure, however, it is recommended to use a simple project with a well-designed folder/file structure.

Sample

1. Start the Eclipse Workbench.

2. Call the Eclipse menu action File / New / Project.

3. Select the required project type and click Next >:

4. Enter a name for the project and confirm the creation with Finish.

5. The "Online Shop" project is created in your local Eclipse workspace. If you cannot see the project, switch to the Eclipse Navigator view.

6. Copy the complete file structure of the base configuration into this local project. Either use the features of your operating system (e.g. drag & drop with Windows Explorer), or use the import facilities of Eclipse:


a) Right-click the project node, and select Import. b) In the Import dialog, select File System and click Next >.


c) Specify the destination of the stored base configuration and select its root folder.

7. After you confirmed the import with Finish, the project resources are copied to your local project and are visible in the Navigator view:


Now that the base configuration has been imported into a local Eclipse project, continue the migration with creating an SCM project.

4.4 Creating an SCM Project After having imported the base configuration into a local Eclipse project, you continue the migration with the creation of the corresponding SCM project.

Sample

1. Right-click the local project and select Team / Share Project. The Share Project wizard is opened where you select the software configuration management system you want to use.

2. Select SCM and click Next >. If you have only one SCM system installed, the SCM wizard page is displayed automatically.


3. Enter the location of your SCM repository and authenticate yourself. Refer to the topic "Adding a repository" in the Interstage ADM Software Configuration Management User Guide (online help) for details about the input fields.

4. Specify a project user group defining the users who will get access rights to all project resources. This user group must have been defined within your company domain, and contain all project members. By default, this group has full access to all project resources. The group must be known to the host on which the SCM repository is running.

After having confirmed the dialog with Finish, the project is created in the specified SCM repository.

5. Import all resources contained in the project. If your project contains several thousand resources, have a look at sections 4.1, Preparations and 2.2, Migrating Large Projects. Right-click the project folder and select Team / Commit.

6. Enter a comment and make sure to check the Include new resources check box. Then start the import by clicking OK.


7. Now all resources are stored in the SCM repository. You can take a look at the structure by changing to the Interstage SCM perspective and expanding the repository node. Refresh the view by pressing [F5] if you cannot see the newly created project.

Proceed with defining the first release in SCM.

4.5 Defining a Release After you have created the SCM project, proceed with defining the first release in SCM. The version number can be specified in accordance with the version number of the imported base configuration.


Sample

1. Right-click the release node in the Navigator SCM view and select Rename. Enter the correct release name and confirm the dialog with OK.

2. To protect the imported base configuration, finally create a snapshot of the MAIN configuration: Right-click the MAIN configuration and select New / Snapshot.


Enter a name for the snapshot and confirm the dialog with OK.

4.6 Rebuilding the Version History The easiest and fastest way for using SCM is to migrate the latest version of your project as base configuration. However, this has one drawback: the version history is lost and can no longer be used for comparison purposes, since every resource is imported as version [1]. In many cases, this is sufficient, because it is still possible to check out or export the base configuration to the file system and use 3rd party tools for comparing the file structures.

If you want to migrate more than one stored build, you can rebuild the resource history by performing the following SCM actions:

1. Define a project.

2. Import the first release [1.00].

3. Close the release and create a new follow-up release [2.00].

4. Assign the newly created [2.00] MAIN configuration to your local project from where you have imported version [1.00].

5. Delete all resources in your local project except the SCM meta-info folder ".escm" (located below the root folder of the project). This step is required for handling deleted files of [2.00] correctly.

6. Update your local project with all resources from version [2.00]. Now you have all meta information from [1.00] and all resources from [2.00] in your local project.

7. Add or commit all resources to the repository. This will import newly added or changed files only to the repository.

8. Close the release and create a new follow-up release [3.00].

9. Repeat the steps above until your version history is complete.


5 After the Migration The following steps should be performed on the target SCM repository after a new project has been successfully imported.

• User administration Customize user and role definitions for the project.

• Ignore patterns Define ignore patterns for project resources, which should not be controlled by SCM.

• Define access rights and groups Define individual access rights and groups for the project.

5.1 Setting up Roles and Authorities Before the project team can use the SCM project, you need to specify specific project roles for each developer. Roles define which SCM actions can be performed by the individual developers.

The person who has imported the project is automatically assigned the default superuser role.

Sample

1. Right-click the project node in the Navigator SCM view and select Users and Roles.

2. Define all roles for the project team and confirm the dialog with OK.

Refer to the Interstage ADM Software Configuration Management User Guide (online help) for details on user and role administration.

5.2 Defining Ignored Resources As one of the final actions in setting up SCM, specify "ignored resources". Such resources are skipped by SCM during recursive actions like commit or update. Ask your project manager or technical leader about the wildcard filters required for this project. In addition, extensions for files of type "text" can be stored for each project entity. Text files can be merged automatically and will be scanned for change report statistics.

Sample

1. Right-click the newly created project in the Interstage SCM perspective, and select Properties.

2. Select Ignored Resources to display the list of currently defined ignore patterns, for example:


3. Add or remove patterns and confirm your settings with OK. The settings become active for all users who access this SCM project.

Refer to the Interstage ADM Software Configuration Management User Guide (online help) for details on ignore patterns.

5.3 Creating Developer Workspaces After having successfully migrated to SCM, developers must check out the working configuration once before they can continue their development work.


Sample

1. Select the migrated working configuration in the Navigator SCM view and select Check Out As New Project. By default, accept the displayed values and confirm the dialog with OK.

2. After the working configuration has been checked out to the local workspace, the developer may continue his/her work and make use of all features of SCM.

Refer to the Interstage ADM Software Configuration Management User Guide (online help) for details.


Appendix A Migration Mapping File

The following section shows the syntax for the mapping file which is needed for the SCM migration. It describes the SCM project structure. By default the mapping file is stored in <project folder>/mapping.xml, where <project folder> is the directory you specified for the export of the project.

Syntax reference:

<!ELEMENT migrationmapping (project*)>

<!ATTLIST migrationmapping version CDATA #IMPLIED >

• version - the minimum required SCM version. The format of the value is <MAJOR VERSION>.<MINOR VERSION>.<BUILD VERSION>. The attribute is optional. When specified, the SCM Import Module checks the version level. The import process fails with a corresponding error message, if the version is not compatible.

<!ELEMENT project (accessgroups?, configuration*)>

<!ATTLIST project name CDATA #REQUIRED creation CDATA # IMPLIED creator CDATA # IMPLIED stricttaskcontrol (false|true) "false" adminrolecheck (false|true) "false" monitoringrequired (false|true) "false" >

• name - the name of the project. The maximum length is 80 bytes. • creation - the creation date of the project. The format is yyyy-MM-dd HH:mm:ss,

GMT+0. • creator - the user Id of the creator. • stricttaskcontrol - a Boolean flag. Value is "true" if strict change request control

should be enabled for the project, or “false” otherwise. • adminrolecheck - a Boolean flag. Value is "true" if the role check is to be enabled

for repository administrators for the project, or “false” otherwise. • monitoringrequired - a Boolean flag. Value is "true" if using monitoring local

changes is to be enforced for the project, or “false” otherwise.


<!ELEMENT accessgroups (accessgroup*)>

<!ELEMENT configuration EMPTY>

<!ATTLIST configuration id CDATA #REQUIRED label CDATA #REQUIRED predecessor CDATA #REQUIRED escmname CDATA #REQUIRED release CDATA #REQUIRED open CDATA #REQUIRED state CDATA #IMPLIED type (release | branch-release | configuration) #REQUIRED creation CDATA #IMPLIED creator CDATA #IMPLIED >

• id - a project unique identifier of the configuration. • label - the label of the configuration that will be used. Format is <release

name>_<cvslabel name> for CVS, $/<release path>$<label> for VSS. • predecessor - the label value of the predecessor configuration. This is empty if

this is the first configuration. Format is <release name>_<configuration name>.

• escmname - the name of the configuration as it appears in SCM. • release - the name of the SCM release, to which the configuration will belong. • open - a Boolean flag. Value is "true" if the configuration or release is to be open,

or “false” otherwise. • state - the state of the configuration (optional). This state must be defined in the

exported template of configuration states. • type - the type of the configuration. Possible values are: „release”, “branch-

release”, “configuration”. The value must be “configuration” if the predecessor configuration is from the same release. The value “release” defines it as first configuration of a follow-up release. The value “branch-release” as first configuration of a branch release.

• creation - the creation date of the configuration. Time format is yyyy-MM-dd HH:mm:ss, GMT+0.

• creator - the user Id of the creator.


<!ELEMENT release (linked*)>

<!ATTLIST release name CDATA #REQUIRED description CDATA #IMPLIED creation CDATA # IMPLIED creator CDATA # IMPLIED >

• name - the name of the release. This must match to a release attribute of a configuration element.

• description - an optional description text for a release comment. Maximum length is 512 bytes.

• creation - the creation date of the configuration. Time format is yyyy-MM-dd HH:mm:ss, GMT+0.

• creator - the user Id of the creator.

<!ELEMENT linked EMPTY>

<!ATTLIST linked configuration CDATA # IMPLIED release CDATA #REQUIRED project CDATA #REQUIRED repository CDATA #IMPLIED server CDATA #IMPLIED hidden CDATA #IMPLIED port CDATA #IMPLIED proxyport (false|true) #IMPLIED target CDATA #IMPLIED virtual (false|true) “true” >

The optional linked element can be used to assign linked releases to this project, which are hosted on any SCM repository.

• configuration - the name of the configuration for the linked release. • release - the name of the linked release. • project - the name of the project for the linked release. • repository - the name of the SCM repository hosting the linked release. • server - the name or IP address of the server for the linked release. • hidden – hides the linked release. • port - the port number for the connection to the linked release. • proxyport - a Boolean switch. "true", if an SSL proxy port should be used for the

connection to the linked release. • target - the name of the target project. • virtual - a Boolean switch. This must be "true" only, if this linked release is a non-

browseable release. If the value is false the attributes configuration, repository, server, port, hidden and target must be specified as well.


<!ELEMENT accessgroup EMPTY>

<!ATTLIST accessgroup name CDATA #REQUIRED >

• name - the name of the access group. Example: The following is an example of a project mapping file:

<?xml version="1.0" encoding="UTF-8" ?>

<migrationmapping version="3.8.3">

<project creation="2005-08-18 13:52:05" creator="ESTESCMTSTXP\Test" name="Project B" stricttaskcontrol="false">

<accessgroups> <accessgoup name="ESTESCMTSTXP\Escm" /> </accessgroups>

<configuration creation="2005-08-16 12:17:00" creator="ESTESCMTSTXP\Test" escmname="Build 1_pre" id="1.0_Build 1_pre" label="1.0_Build 1_pre" open="false" release="1.0" state="qa" type="release" />

<configuration creation="2005-08-16 12:17:04" creator="ESTESCMTSTXP\Test" escmname="Build 2" id="1.0_Build 2" label="1.0_Build 2" open="false" predecessor="1.0_Build 1_pre" release="1.0" state="archived" type="configuration" />

<configuration creation="2005-08-16 12:17:07" creator="ESTESCMTSTXP\Test" escmname="Build 123" id="1.0_Build 123" label="1.0_Build 123" open="false" predecessor="1.0_AUTOBUILD_08.06.2005_18-34-44-15" release="1.0" state="archived" type="configuration" />


<configuration creation="2005-08-16 12:17:11" creator="ESTESCMTSTXP\Test" escmname="MAIN" id="1.0_MAIN" label="1.0_MAIN" open="true" predecessor="1.0_AUTOBUILD_13.07.2005_15:32:04,02" release="1.0" state="in development" type="configuration" />

<configuration creation="2005-08-16 12:17:12" creator="ESTESCMTSTXP\Test" escmname="Build 2.1" id="2.1_Build 2.1" label="2.1_Build 2.1" open="false" predecessor="1.0_Build 1_pre" release="2.1" state="released" type="release" />

<release creation="2005-08-16 11:19:38" creator="ESTESCMTSTXP\Test" name="1.0" />

<release creation="2005-08-16 16:28:51" creator="ESTESCMTSTXP\User2" description="Emergency release" name="2.1">

<linked configuration="" hidden="false" port="9700" project="Project A" proxyport="false" release="2.0" repository="ESCM212" server="estescmtstxp" target="Project A" virtual="true" />

<linked configuration="" hidden="false" port="9700" project="Project B" proxyport="false" release="1.0" repository="ESCM212" server="estescmtstxp" target="Project B" virtual="true" />

<linked project="Java JDK" release="1.4.2" />

</release> </project> </migrationmapping>


Appendix B Environment XML Files

The following section shows the syntax for the environment files which are created during the SCM migration.

B.1 Export Environment File The export environment file is stored in <project folder>/ExportEnv.xml, where <project folder> is the directory you specified for the export of the project.

Syntax reference:

<!ELEMENT environment (exporter.properties | source.properties |System.properties)>

<!ELEMENT property EMPTY>

<!ATTLIST property name CDATA #REQUIRED value CDATA #REQUIRED >

<!ELEMENT exporter.properties (property*)>

The section exporter.properties lists properties of the used SCM export module as key value pairs. The following export properties are provided:

• SCM Export Module - the used SCM export module version. • Java VM - the version of the used Java Virtual Machine. • Export call – the export call with all option arguments (only for the export of SCM

projects).

<!ELEMENT source.properties (property*)>

The section source.properties lists properties of the source software configuration management system as key value pairs. The following export properties are provided:

• Source SCM - the name of the source software configuration management system. • Source server - the name and/or IP address of the source server. • Repository – the name or path of the source repository. • Project – the name or path of the source project.

<!ELEMENT system.properties (property*)>

The system.properties section lists the system properties which are set on the host where the export was executed as key value pairs. They depend on the version of the used Java runtime environment (JRE) and on other applications which might set, add or remove such properties. These are the properties returned by the java.lang.System.getProperties() method. For a default set of properties, refer to the Java documentation of this method in the affected Java version.


B.2 Import Environment File The import environment file is stored in <project folder>/ImportEnv.xml, where <project folder> is the directory you specified for the import of the project.

Syntax reference:

<!ELEMENT environment (importer.properties | target.properties | system.properties)>

<!ELEMENT property EMPTY>

<!ATTLIST property name CDATA #REQUIRED value CDATA #REQUIRED >

<!ELEMENT importer.properties (property*)>

The section importer.properties lists properties of the used SCM import module as key value pairs. The following import properties are provided:

• SCM Import Module - the name and version of the SCM import module. • Java VM - the version of the used Java Virtual Machine. • Import call - the import call with all option arguments.

<!ELEMENT target.properties (property*)>

The section target.properties lists properties of the target SCM system as key value pairs. The following import properties are provided: • SCM - the SCM version of the target system. • Target server - the name and/or IP address of the target host. • Target repository - the name of the target SCM repository. • Target project - the name of the target SCM project.

<!ELEMENT system.properties (property*)>

The system.properties section lists the system properties which are set on the host where the import was executed as key value pairs. They depend on the version of the used Java runtime environment (JRE) and on other applications which might set, add or remove such properties. These are the properties returned by the java.lang.System.getProperties() method. For a default set of properties, refer to the Java documentation of this method in the affected Java version.


Appendix C Migration Commands This appendix describes the migration commands and their syntax.

Notational Conventions for Syntax Descriptions

In keeping with the usage messages, which appear on your screen, the following notational conventions are used in the syntax descriptions for the command line interface commands:

< > Variable entry [ ] Optional entry { … | ... } Alternative entry

Overview

A command call generally looks like this:

{escmmigration | escmvssmigration} <command> [options] [arguments]

To invoke the command <command> with the escmmigration.bat/escmvssmigration.bat batch file or escmmigration.sh shell script.

{escmmigration | escmvssmigration} --help

To get help about the general usage of the escmmigration.bat/escmvssmigration.bat batch file or escmmigration.sh shell script.

{escmmigration | escmvssmigration} -- help <command>

To get help about the usage of the specified command, <command>, of the escmmigration.bat/escmvssmigration.bat batch file or escmmigration.sh shell script.

export – Export an SCM project

Exports an SCM project to the file system.

The export command exports the whole project including all resource versions to a specified directory in the file system.

Command Syntax:

escmmigration export [-multi] –s <server> –d <repository> –u <user> –pw <password> –p <project> [-po <port>] <export path>


-multi Specify this option if you want to export huge projects in several repeated steps which will only export snapshots. After the last migration import has been executed, the migration of the project can be finished by omitting this option which will export the remaining configurations.

-s <server> Name of the server where the Interstage SCM repository is located.

-d <repository> Name of the Interstage SCM repository which contains the project to be exported.

-u <user> Name of the user which is to be used for repository authentication.

-pw <password> Password of the user which is to be used for repository authentication.

-p <project> Name of the project to export.

-po <port> Port to access the repository server. The default port is 9700.

<export path> Path and name of the exported project.

export – Export a VSS project

Exports a VSS project to the file system.

Command Syntax:

escmvssmigration export [-a] -p <project> -v <VSS database folder> -u <VSS user> -t <target folder> [-pw <VSS password> -m <mapping file>]

-a Exports the user access rights for resources.


-v <VSS database folder> Folder of the VSS database from which the project is to be exported. This is the folder which contains the srcsafe.ini file of the database.

-u <VSS user> User name for the VSS database to be used during the export.

-t <target folder> Path and name of the destination folder in which to export the data.

-pw <VSS password> Password of the VSS user. Depending on the settings in the VSS database, the export may also work without specifying the password.

-m <mapping file> Path and name of the XML file containing the project mapping.


import – Import an SCM project

Imports an exported SCM structure as a new SCM project.

Command Syntax:

escmmigration import [-disav –multi -skipres] –ts <server> –td <repository> –u <user> –pw <password> –tp <project> -g <group> [-tpo <port> -delcfg <configuration>] <import path>

-disav Disables the automatic modification of commit comments which, by default, appends the author and version information to the commit comment of each resource version.

-multi Specify this option if you want to import huge projects in several repeated steps. After the last migration import has been executed, the migration of the project can be finished by omitting this option.

-skipres Skips the whole import of the resource versions. In this case, it is assumed that all required versions already have been imported to the target repository. If specified, only the configuration structures are created.

-ts <server> Name of the target server where the Interstage SCM repository is located.

-td <repository> Name of the Interstage SCM repository to which the project is to be imported.



-tp <project> Target project which is to be created from the exported data.

-g <group> Up to eight (semicolon-separated) user groups known to the repository server, whose members can work in the new project.

-tpo <port> Port to access the repository server. The default port is 9700.

-delcfg <configuration> Deletes the specified configuration without doing any further import process. This option is only required for multiple imports. In contrast to the normal delete operation of SCM, resources are not checked and/or moved to the Lost & Found folder. All working configurations, which have been changed by the users in the meantime, must be deleted before a repeated import. Already existing configurations are not recreated during a repeated import.

<import path> Path and name of the imported project.


move – Move an SCM project to another repository

Moves a project from one location to another. This command combines the export and import command. It first exports the whole project including all resource versions to the specified target directory and then imports it as a new project.

Command Syntax:

escmmigration move –s <server> –d <repository> –u <user> –pw <password> –p <project> –ts <target server> –td <target repository> –tp < target project> -g <group> [-po <port> -tpo < target port>] <export path>]

-s <server> Name of the server where the Interstage SCM repository is located.

-d <repository> Name of the Interstage SCM repository which contains the project to be exported.




-ts <target server> Name of the target server where the Interstage SCM repository is located.

-td <target repository> Name of the Interstage SCM repository to which the project is to be imported.

-tp <target project> Target project which is to be created from the exported data.

-g <group> Up to eight (semicolon-separated) user groups known to the repository server, whose members can work in the new project.

-po <port> Port to access the repository server. The default port is 9700.

-tpo <target port> Port to access the target repository server. The default port is 9700.




usermapping – Create default mapping for users and groups

Maps the users and user groups of the exported project to the users and groups of the target project.

An exported project might contain users and user groups that are unknown to the target import environment. In order to import such projects, a mapping for the users and groups must be performed. The usermapping command creates a default mapping which contains empty mappings for all users and groups occurring in the exported project. The mapped users and groups must be edited afterwards, before the import is executed.

This command may only be executed on a successfully exported project structure.

Command Syntax:

escmmigration usermapping <export path>


Documents

Interstage ADM Software Configuration Management Migration ...software.fujitsu.com/jp/manual/manualfiles/M080264/... · This manual describes how to migrate projects from other software