Interstage Application and Service Management V10.0. Interstage ADM Software Configuration Management Migration Guide

Transcription

1 Interstage Application and Service Management V10.0 Interstage ADM Software Configuration Management Migration Guide B1WD ENZ0(00) October 2008

2 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

3 Contents 1 Introduction Before the Migration Optimizing the Project Structure Migrating Large Projects Preparing the SCM Environment Creating a Backup Automated Migration Migration in steps Preparations...15 System Requirements Creating a Target Directory Providing Sufficient Disk Space Preparing the Command Line Interface Usage Considering Memory Requirements Considering the Duration of a Migration Logging Commit comments Copying the exported structure Restrictions Automatically Migrating CVS Projects...20 Preparations Defining the Export Target Defining the SCM Project Structure Starting the Export Resuming an Aborted Export Multiple Export Restrictions Automatically Migrating VSS Projects Preparations Defining the Project Mapping Starting the Export Error Handling Resuming an Aborted Export Restrictions...38 Interstage ADM Software Configuration Management Migration Guide 3

4 3.5 Importing into SCM Multiple Import Creating the User Mapping Handling comments Importing the Project Manual Migration Preparations Defining a Base Configuration...43 CVS Base Configuration RCS Base Configuration VSS Base Configuration Removing Administrative Resources Creating a Local Eclipse Project Creating an SCM Project Defining a Release Rebuilding the Version History After the Migration Setting up Roles and Authorities Defining Ignored Resources Creating Developer Workspaces...57 Appendix A Migration Mapping File Appendix B Environment XML Files B.1 Export Environment File...64 B.2 Import Environment File...65 Appendix C Migration Commands Interstage ADM Software Configuration Management Migration Guide 4

5 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 Interstage ADM Software Configuration Management Migration Guide 5

6 Notational Conventions This manual uses the following notational conventions: Add init <variable> [option] {one two} Abbreviations The names of graphical user interface elements like menu options are shown in bold case. System names, for example, command names, and text that is entered from the keyboard are shown in Courier font. Variables for which values must be entered are enclosed in angle brackets. Optional items, for example, optional command options, are enclosed in square brackets. Alternative entries are enclosed in curly brackets and separated by a vertical bar. This manual uses the following abbreviations for Interstage products and components: Interstage ASM Interstage BPM Interstage ADM Interstage SQA CHM COC DMS LCM QAM RLM RQM SCA SCM Interstage Application and Service Management suite Interstage Business Process Manager Interstage Application Development Cycle Manager product of Interstage ASM Interstage Software Quality Analyzer product of Interstage ASM Change Management component of Interstage ASM Control Center component of Interstage ASM Document Management component of Interstage ASM Lifecycle management components (CHM, RLM, RQM) of Interstage ASM Quality Assessment component of Interstage ASM Release Management component of Interstage ASM Requirements Management component of Interstage ASM Source Code Analysis component of Interstage ASM Software Configuration Management component of Interstage ASM The term "Windows" is used to denote the different Microsoft Windows operating systems supported by Interstage ASM. Interstage ADM Software Configuration Management Migration Guide 6

7 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. Interstage ADM Software Configuration Management Migration Guide 7

8 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. Interstage ADM Software Configuration Management Migration Guide 8

9 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 Interstage ADM Software Configuration Management Migration Guide 9

10 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. Interstage ADM Software Configuration Management Migration Guide 10

11 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: Interstage ADM Software Configuration Management Migration Guide 11

12 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): (corresponds to a maximum file size of 80 MB) SCM Default (since 2.1): (corresponds to a maximum file size of 800 MB) Interstage ADM Software Configuration Management Migration Guide 12

13 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: 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 ,000 6,000 1, ,000 10,000 3,000 1,000 40,000 50,000 10,000 2,500 50,000 80,000 20,000 3, , ,000 30,000 4, , ,000 > 40,000 > 5, , ,000 Default SCM settings: 50, ,000 Interstage ADM Software Configuration Management Migration Guide 13

14 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! Interstage ADM Software Configuration Management Migration Guide 14

15 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 and 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. Interstage ADM Software Configuration Management Migration Guide 15

16 3.2.1 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. Interstage ADM Software Configuration Management Migration Guide 16

17 3.2.3 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> Interstage ADM Software Configuration Management Migration Guide 17

18 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 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 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. Interstage ADM Software Configuration Management Migration Guide 18

19 Example entry for an exported version: [ :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 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. Interstage ADM Software Configuration Management Migration Guide 19

20 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). Interstage ADM Software Configuration Management Migration Guide 20

21 The following steps are involved in performing a complete migration from CVS to SCM: Preparations 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 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. 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. Interstage ADM Software Configuration Management Migration Guide 21

22 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. Interstage ADM Software Configuration Management Migration Guide 22

23 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. Interstage ADM Software Configuration Management Migration Guide 23

24 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. Interstage ADM Software Configuration Management Migration Guide 24

25 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. Interstage ADM Software Configuration Management Migration Guide 25

26 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. Interstage ADM Software Configuration Management Migration Guide 26

27 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. Interstage ADM Software Configuration Management Migration Guide 27

28 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 followup 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. Interstage ADM Software Configuration Management Migration Guide 28

29 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 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. Interstage ADM Software Configuration Management Migration Guide 29

30 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 , 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 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). Interstage ADM Software Configuration Management Migration Guide 30

31 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 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 Preparations 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. 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. Interstage ADM Software Configuration Management Migration Guide 31

32 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 subtree 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. Interstage ADM Software Configuration Management Migration Guide 32

33 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"/> <configuration escmname="l2" id="r1_l2" label="$/myproject1.0$l2" 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"/> <configuration escmname="l1" id="r2_l1" label="$/myproject2.0$l1" open="false" predecessor="r1_l1" release="r2" state="archived" type="release"/> <configuration escmname="l2" id="r2_l2" label="$/myproject2.0$l2" open="false" predecessor="r2_l1" release="r2" 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: E.g.: $/<release path>$<label> 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. Interstage ADM Software Configuration Management Migration Guide 33

34 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. Interstage ADM Software Configuration Management Migration Guide 34

35 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. Interstage ADM Software Configuration Management Migration Guide 35

36 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 # 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 READ CHECK OUT ADD DESTROY SCM READ WRITE WRITE WRITE Interstage ADM Software Configuration Management Migration Guide 36

37 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 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: f3: 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. Interstage ADM Software Configuration Management Migration Guide 37

38 3.4.4 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 subtree 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). Interstage ADM Software Configuration Management Migration Guide 38

39 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 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 Interstage ADM Software Configuration Management Migration Guide 39

40 For details on the command syntax, refer to Appendix C, Migration Commands. 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> 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 Importing the Project After having created a user mapping file (see above), you finally import the project structure from the file system into SCM. Interstage ADM Software Configuration Management Migration Guide 40

41 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 For details on the command syntax, refer to Appendix C, Migration Commands. Interstage ADM Software Configuration Management Migration Guide 41

42 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. Interstage ADM Software Configuration Management Migration Guide 42

43 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. Interstage ADM Software Configuration Management Migration Guide 43

44 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 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 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). Interstage ADM Software Configuration Management Migration Guide 44

45 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 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: Interstage ADM Software Configuration Management Migration Guide 45

46 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. 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. Interstage ADM Software Configuration Management Migration Guide 46

47 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. Interstage ADM Software Configuration Management Migration Guide 47

48 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: Interstage ADM Software Configuration Management Migration Guide 48

49 a) Right-click the project node, and select Import. b) In the Import dialog, select File System and click Next >. Interstage ADM Software Configuration Management Migration Guide 49

50 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: Interstage ADM Software Configuration Management Migration Guide 50

51 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. Interstage ADM Software Configuration Management Migration Guide 51

52 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. Interstage ADM Software Configuration Management Migration Guide 52

53 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. Interstage ADM Software Configuration Management Migration Guide 53

54 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. Interstage ADM Software Configuration Management Migration Guide 54

55 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. Interstage ADM Software Configuration Management Migration Guide 55

56 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: Interstage ADM Software Configuration Management Migration Guide 56

57 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. Interstage ADM Software Configuration Management Migration Guide 57

58 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. Interstage ADM Software Configuration Management Migration Guide 58