Perforce Consulting Guide

This document helps you plan to migrate from legacy ClearCase to Perforce.

• Get detailed strategies for migrating• Weigh the pros and cons—from starting over to

selective and exhaustive—of different file history import strategies

Migration Planning Guide:

IBM Rational ClearCase to Perforce

Migration Planning Guide: IBM Rational ClearCase to Perforce

Table of Contents

Introduction_________________________________________________________________________ 1Preliminary_Migration_Preparation________________________________________________________ 1

Reviewing_Existing_Branching_Strategy_________________________________________________ 1Planning_the_Directory_Structure_ ____________________________________________________ 1Defining_Release_Processes_and_Directory_Structure_Standards_______________________________ 1Perforce_Streams__________________________________________________________________ 1Addressing_Intellectual_Property_Concerns______________________________________________ 2Training________________________________________________________________________ 2Transition_Team_ _________________________________________________________________ 2

Import_Strategies_____________________________________________________________________ 2Starting_Over_(Tips)________________________________________________________________ 2

Pros_of_Starting_Over___________________________________________________________ 3Cons_of_Starting_Over__________________________________________________________ 3

Detailed_History_Import_ ___________________________________________________________ 3Preparation_for_a_ClearCase_Detailed_History_Import_______________________________________ 3Extracting_and_Importing____________________________________________________________ 4Custom_Scripting_ ________________________________________________________________ 4Full_vs._Sparse_Context_Strategies_____________________________________________________ 4

Pros_of_a_Full_Context_Import_____________________________________________________ 4Cons_of_a_Full_Context_Import_ ___________________________________________________ 4Pros_of_a_Sparse_Context_Import_ _________________________________________________ 5Cons_of_a_Sparse_Context_Import__________________________________________________ 5

Hardware_Capacity_Planning_________________________________________________________ 5Pros_of_a_Detailed_History_Import__________________________________________________ 5Cons_of_a_Detailed_History_Import_________________________________________________ 5

Baseline_and_Branch_Import_(BBI)_____________________________________________________ 5Pros_of_a_BBI_Strategy___________________________________________________________ 6Cons_of_a_BBI_Strategy__________________________________________________________ 7Limitations_ _________________________________________________________________ 7

Terminology_and_Concepts______________________________________________________________ 7VOBs_and_Depots_ ________________________________________________________________ 7Regions_and_Protections____________________________________________________________ 7VOB_Servers_and_the_Perforce_Server___________________________________________________ 8

Operating_System_Selection______________________________________________________ 8Registry_and_License_Servers_________________________________________________________ 8Release_Servers_and_Installation______________________________________________________ 8View_Servers,_Protecting_Unversioned_and_Checked-Out_Files________________________________ 8ClearCase_MultiSite_versus_Perforce_Proxies_ ____________________________________________ 9ClearCase_Views_with_Perforce_Workspaces_____________________________________________ 9Label_Strategies_ _________________________________________________________________ 9Unified_Change_Management_(UCM)_________________________________________________ 10Migration_Technical_Details_________________________________________________________ 10

Evil_Twins___________________________________________________________________ 10Symlinks_on_Windows_________________________________________________________ 10File_Type_Mappings_and_Limitations_______________________________________________ 10

Learn_More_________________________________________________________________________ 11Perforce_Knowledge_Base_Articles____________________________________________________ 11Perforce_Directory_Standard_Template_________________________________________________ 11Branching_Strategies_and_Best_Practices_Implementation__________________________________ 11Perforce_Comparisons_____________________________________________________________ 11Perforce_Consulting_Services________________________________________________________ 11

Migration_Planning_Checklist___________________________________________________________ 12

Migration Planning Guide: IBM Rational ClearCase to Perforce1

IntroductionThis document tells you how to plan to migrate from legacy ClearCase to Perforce and discusses strategies for importing file history. Basic familiarity with ClearCase architecture, concepts, and terminology is helpful but not necessary when reading this document. Any necessary Perforce concepts and terminology will be explained. In particular, three history import strategies are reviewed: starting over (Tips), detailed history import (DHI), and baseline and branch import (BBI).

ClearCase-to-Perforce migration projects vary greatly in scale and complexity. Small, simple environments with basic migration requirements are typically migrated in about eight business days, including setting up Perforce, migrating, and training users and administrators. Large, complex ClearCase environments might perform a series of migrations over the course of several months or more, because individual teams migrate at convenient times.

This document is not intended to replace an assessment of your environment. An assessment helps you focus on factors that are relevant to your environment to produce a custom migration strategy. For assistance with your Perforce migration, visit perforce.com/consulting.

Preliminary Migration PreparationThe following factors inform a migration strategy from ClearCase to Perforce.

Reviewing Existing Branching StrategyEarly in migration planning, determine whether the branching strategy that you used in ClearCase is appropriate to use with Perforce. If not, decide on the strategy you intend to use with Perforce. Creating an initial branching strategy is a best practice when getting started in Perforce in any case, more so in a migration scenario if you are going to preserve any history.

Planning the Directory StructureWith Perforce’s Inter-File Branching™ mechanism, the directory structure and branch model are related, unless Perforce Streams are used. A well-defined directory structure helps convey branch structure and software lifecycle information, making it intuitive to use. After a branching strategy is identified, you can map it to a high-level directory structure, or Perforce Directory Standard (PDS), in Perforce. See Additional Resources

at the end of this document to download a template for developing your own PDS.

Defining Release Processes and Directory Structure StandardsThink of the directory structure in Perforce as having low and high levels. Low levels contain your software products. High levels define branching structure, project management, and software lifecycle information. A well-designed high-level directory structure is intuitive for developers and lends itself well to project management metrics, policy enforcement by branch type, and automation.

Migrating to Perforce typically involves defining a Perforce Directory Standard for each product imported into Perforce and, in some cases, for your entire organization. The high-level structure encourages consistency in release processes for various software products but can be flexible to allow different software products to have different release processes. For example, one software product might be a licensed software product, the release process for which defines how old releases are maintained and patched. A web-based software product operated in your own data center follows a different release process, with little need to maintain old releases but a requirement for rapid updates. Still another product might be a set of generic components that are delivered to customers and then heavily customized, perhaps by your own professional services organization.

Release processes for different software products might vary because of the number of contributors and the degree of structure of QA processes. Software products can follow the same release process, even though they have different release schedules.

To minimize the difficulty and impact of migration, the low levels of the directory structure (for example, build scripts, release processes and tools, and so on) are untouched.

Perforce StreamsStreams model branches at a higher level. A stream defines a set of related files, where those files came from (the parent stream), how change flows to other streams, and how parts of a stream are treated in the workspace.

Although many of the concepts in the PDS are still relevant when using streams, the implementation details are different. The PDS points out those differences as a starting point for discussion.

Migration Planning Guide: IBM Rational ClearCase to Perforce 2

Streams are an attractive framework for new projects in Perforce. The tools and workflow improvements simplify work for end users and make project and release management easier.

The detailed history import (DHI) tool used by Perforce does not currently allow ClearCase data to be imported directly as streams. However, ClearCase data can be imported into regular Perforce branches and then migrated to streams for future work. Alternatively, the baseline and branch import (BBI) method can be used to import ClearCase data into streams.

Addressing Intellectual Property ConcernsKnowing where your source code came from and knowing what legal rights you have to it can be a priority when migrating to a new software version management system. Ensure that the migration does not affect intellectual property provenance. Your migration processes must provide a clear audit trail so all imported files can be traced back to the original ClearCase repository.

Software version management systems store valuable intellectual property. If sensitive information is being migrated, both the migration process and the resulting Perforce environment must ensure that access is controlled as well as it was in ClearCase.

Migrations provide an opportunity to review access control policies. In some cases, ensuring protections of intellectual property requires extra effort. In other cases, migrations expose particularly weak access controls, and Perforce’s powerful and flexible access control capabilities provide a straightforward means of guarding intellectual property.

TrainingTo ensure a smooth migration, and to help users get the most from Perforce after a migration, training for Perforce users and administrators is essential. It is most effective to train most of your users a few days or weeks before the cutover to Perforce.

Perforce provides both on-demand eLearning and instructor-led training. An effective strategy is to provide instructor-led training to a core set of administrators and key users, and provide eLearning to the bulk of the users.

Transition TeamWe recommend establishing a transition team—a core group that includes application administrators, system

administrators, and other influential users—to define how Perforce will be used in your organization, how it will tie into your various processes and workflows, and how to integrate it with other systems. You may even wish to engage Perforce Consulting to be a part of your transition team.

For larger, more complex, migrations we recommend the transition team members take Perforce training early in the planning process. This allows for best practices established by the team to evolve, be documented, and proliferate during the training of the larger user community later in the migration process.

Import StrategiesThere are three approaches for importing files:

• Starting over (Tips).• Detailed history import (DHI), which can be

exhaustive or selective.• Baseline and branch import (BBI), which is

inherently selective.

Selective means that, within a given branch, details of activities performed can be propagated to Perforce, including file contents at each revision and the user ID/date/time/check-in comment associated with each check-in.

The following sections present an overview of the strengths and limitations of each import strategy.

Starting Over (Tips)This strategy involves getting the latest file versions, or “tips,” from ClearCase and adding them to Perforce. No history is preserved.

Define a high-level directory where the files will be stored, for example: //Eng/Gizmo/MAIN/src

In the preceding example, Eng stands for Engineering, Gizmo is a product name, MAIN indicates files in the main stream of development, and src is the root of the low-level directory tree. The low-level directory tree is copied into Perforce.

This approach is sometimes appropriate for documentation VOBs or VOBs for shelved (but not terminated) projects. It is rarely ideal for source code, except for prototype and demo code.

Migration Planning Guide: IBM Rational ClearCase to Perforce3

Pros of Starting Over

• Easy: You only need to define target directories in Perforce and then add the files.

• Fast.• No undesirable metadata in Perforce.

Cons of Starting Over

• No historical information is available in Perforce.

Detailed History ImportThis strategy is the most complete case of conversion, and captures as much detailed branch/merge information as possible so that comprehensive historical research can be done in the new system without requiring the old one.

Published, supported tools exist that import history from CVS, RCS, VSS, and Subversion to Perforce. Perforce Software has a sophisticated tool and process, currently only available as a service, that enables conversion of very detailed historical data from ClearCase to Perforce. The tool has been successfully used for performing detailed history conversions from fairly large ClearCase data sets (about 100 GB) to Perforce.

Detailed history migrations from ClearCase can be selective; a subset of VOBs can be imported, and within each imported VOB, a subset of all available branches and labels targeted for import. Conversion includes file contents at each revision, the userid/date/time/checkin comment associated with each checkin, file renames, and detailed branching and merging history. ClearCase’s representation of branching activity is translated into Perforce “integration records.”

The import process uses heuristics to group ClearCase “checkins” into Perforce “changelists.” For example, if a given user checked-in a set of files at the same time (+/- a few seconds) with the same checkin comment, those will be grouped together as a single Perforce changelist. UCM metadata, if available, also factors into the changelist grouping.

Our migration process starts by scanning repositories for various issues that need to be resolved in ClearCase or otherwise handled manually prior to migration. Examples of things that must be resolved prior to migration include:

• “Evil twin” files and directories.• Unusual historical patterns, such as changing the

type of an object from a symlink to a directory, and then to a file.

• Architectural and conceptual differences between ClearCase and Perforce. For example, mapping ClearCase labels to Perforce proves rather difficult because typical usage of labels varies between the systems, as well as the underlying implementations.

• Certain rare “circular merge” activities. • Mild data corruption in ClearCase repositories

that normally might not be visible, but is exposed when running certain commands used by a detailed history conversion tool.

Migrating detailed history from ClearCase is harder than doing so from any other software version management system. Concepts from UCM and RUP that depend on ClearCase attributes, triggers, etc., are not fully handled mechanically. Depending on the amount of data being migrated and the speed of ClearCase, it might require running systems in parallel. The mechanical extraction/import of all the information from a typical ClearCase setup with years of history might take days to perform, and the performance is limited mainly by the speed of ClearCase.

Preparation for a ClearCase Detailed History ImportIf you engage Perforce Consulting to help you plan a detailed history migration from ClearCase, here are a few things to be aware of early in your planning process:

• A replica of your ClearCase environment, including all VOBs targeted for import, should be provisioned on hardware separate from your production environment. This allows dry runs and other data analysis that can be unduly taxing on a production server.

• A powerful, dedicated migration server machine must be available. This could be the new Perforce server machine, and must be a Linux server, even if the production and replica servers are Windows. A fast network connection between the ClearCase replica machine and the migration server (which can be the Perforce server) is essential.

• Migration is a very resource-intensive process, and can be very demanding in terms of disk space and RAM resources. It is more demanding than actual Perforce server operation because years of work in ClearCase are being compressed into hours or days.

Migration Planning Guide: IBM Rational ClearCase to Perforce 4

• 100G of VOB data converts in about 18 hours, which is the maximum amount of time you would want a migration to take. Dealing with larger repositories is possible, but requires more sophisticated migration strategies and more hardware to enable parallel operation of multiple VOBs.

Extracting and Importing Detailed history migrations can be front- or back-door implementations with respect to both extraction from ClearCase and importing into Perforce. Depending on your environment and migration plans, awareness of the capabilities and limitations of each style is important when planning migrations, especially for multi-phased migrations involving multiple teams migrating over time.

Front-door implementations operate as a regular user would, using “cleartool” or “p4” commands to interact with a live, running ClearCase or Perforce server.

Back-door implementations extract data directly from VOB databases, or generate Perforce metadata in the form of a Perforce checkpoint on import, and require the respective servers to be offline.

Perforce Software’s migration tool for ClearCase migrations is “front door” with respect to extraction from ClearCase, and “back door” with respect to importing into Perforce. Being front door on the ClearCase side enables the tool to work across many ClearCase versions, while being back door on the Perforce side allows it to generate the most accurate representations of ClearCase history in terms of Perforce journal records.

Custom ScriptingA detailed migration sometimes involves custom scripting due to differences in ClearCase usage and any oddities in a particular dataset.

Full vs. Sparse Context StrategiesA full context strategy is one in which the goal is to recreate history in Perforce the way it would be if Perforce had been used all along. For example, at the point in time a branch is created, the version of each file intended to be available in the branch is tracked explicitly by an integration record, even if it is never modified on the branch. Years later, there is no need to guess at user intent, and the starting state of the branch is clear.

In ClearCase, however, figuring out what a branch looked like at its start point can be a real challenge for anyone unfamiliar with the branching strategy used at the time any given branch was created. ClearCase does not store the config specs used to create and manage a branch, nor does it provide a definitive way to associate config specs with branches at any point in the future.

Unless the ClearCase administrators enforced a strict policy that saved config specs for every branch (and made them easy to find), reconstructing a ClearCase branch involves educated guesswork. The guesswork is less difficult if important config specs were explicitly versioned and adhered to a consistent naming convention, or were otherwise clearly identified. In cases where that is true, it is possible to develop custom heuristics to generate config specs to more faithfully recreate branch start points.

If the config specs that generate the start point of each branch can be reliably reproduced, that knowledge can be codified into “driver scripts” that point the conversion engine in the right direction. A faithful full-context import is possible in that scenario.

Pros of a Full Context Import

• Lends itself well to doing easy verification.• Full context history makes can be used to run

builds.• Richer understanding of your file history.• File-level merge forensics for any given file is

possible.

Cons of a Full Context Import

• The manual effort required to do a full-context conversion effectively limits the number of branches that can be imported. In large environments, full-context imports generally force a trade-off of limited scope, because only a relatively small number of the most important branches actually get imported.

Typically only major branches are imported with this approach. In some cases, personal development sandboxes are either left behind entirely, or have their checkin comments summarized into a big description applied whenever a file is promoted from the sandbox to the team branch (which is imported).

The alternative to a full context import is a sparse import strategy. This strategy ignores the guesswork, and lends itself well to automated discovery and import of all file-level history from ClearCase on all branches.

Migration Planning Guide: IBM Rational ClearCase to Perforce5

Pros of a Sparse Context Import

• File-level merge forensics is possible for any given file, with history showing only branches that it was modified on.

• It is more practical to attempt full-scope (all or many branch) imports, even on large datasets.

• Much less tool configuration is required, as the “config spec” gathering/generating process is unnecessary.

Cons of a Sparse Context Import

• Branch-level history is unavailable. In Perforce, you see the set of files modified on any given branch and can follow their history, but you cannot see them in the context of the entire branch (including files never modified on the branch).

Hardware Capacity PlanningHardware capacity planning may be impacted significantly with DHI migrations. A software version management system with, for example, 12 years of history would require more hardware (more disk space, more RAM, faster CPUs and I/O subsystems, etc.) than one with no history. If you import 12 years of detailed history, your new Perforce system will initially require as much hardware as if it had been in operation for 12 years.

Pros of a Detailed History Import

• Most complete approach. Detailed history imports can transfer the most historical detail, including branching history, from ClearCase to Perforce.

• After the migration, comprehensive historical research and “merge forensics” can be done in Perforce without the need for going back to ClearCase (we recommmend keeping one user license in ClearCase as a backup).

• The ability to view file history with Perforce’s powerful visualization tools like Time-Lapse View can shed new light on the evolution of source code and help increase understanding of the changes over time.

• There is an increased benefit for systems integrated with version control. For example, the meaning of the linkage between a set of files originally modified in ClearCase and an issue from your issue tracking

system can be maintained. Code review tools such as SmartBear Code Collaborator will have greater context.

• Unlike Perforce, ClearCase does not validate the integrity of versioned file contents using checksums. File corruption, for example, because of disk failures, goes undetected.1 Once historical data is in Perforce, it will gain the benefit of checksum verification of contents of all revisions, which improves IP provenance.

Cons of a Detailed History Import

• Detailed import tools have a variety of limitations and technical caveats. Some limitations are due to differences in the way ClearCase and Perforce work, and some are due to the potential complexity of ClearCase environments, including unusual patterns (or even corruption) in the data. So called “Evil Twin” elements and certain circular branching patterns created by misconfigured config specs can be difficult to follow.

• Existing detailed history import tools may require development to work on your data. The likelihood of this depends on your data, and is typically necessary if a full-context migration is attempted.

• Complexity translates into potential schedule and budget risks for the migration project.

Baseline and Branch Import (BBI)The BBI strategy provides a lightweight migration alternative that is more sophisticated than the Tips approach and avoids the technical complexity and schedule and budget risks of detailed history imports.

BBI is a generic from-anything-to-Perforce process, and has been used to migrate to Perforce from a variety of software version management systems, including IBM Rational ClearCase, Borland StarTeam, Merant PVCS, Subversion, Mercurial, CVS, Microsoft Visual Source Safe, AccuRev, and even unsophisticated “systems” like a set of network drives with directories named for releases.

With the BBI approach, the “interesting history” to be imported is specified using a branch diagram that shows the baselines (snapshots of a directory structure at a specified point in time) and major branching operations. For example, Figure 1 represents a software product. The baselines (blue dots) indicate the “interesting versions” that are to be imported. The arrows indicate branching

1 ClearCase does have a “checkvob” utility that can detect and fix some forms of metadata corruption. However, this utility does not detect data container corruption, and thus the contents of versioned files cannot be audited.

Migration Planning Guide: IBM Rational ClearCase to Perforce 6

operations that affect an entire branch. In this example, a 2.0-Rel branch has been created, and four patches were created from that branch. Two of those four patches have been merged back to MAIN. The BBI process imports all the baselines, records that the two patches were merged with resulting updates to MAIN, and tracks the two unmerged patches. After migrating, you can use Perforce to complete those merges.

Importing the branching operations enables Perforce to select common ancestors when merging, so you can resume branching activities after migration. The BBI process imports branching operations at a high level, capturing the sum of merge operations. For example, in Figure 1, the merge of p2 back to MAIN most likely consisted of a series of merges by several developers. The individual file merges are not tracked, but the sum of the results of the merges (file adds, edits, and deletes) are tracked. The imported baseline represents the point in time when the merge of p2 is complete.

The intent of this approach is to bring over just enough branching history to answer key questions such as what did Release 2.0 look like, where was this file branched from, and what files do I need in my workspace to start maintenance work on Release 2.3? The BBI approach preserves file contents at key points and preserves enough branching history so that the switch to Perforce can happen at any point in the release cycle, rather than just at “convenient points” in the schedule (which tend to be hard to find).

After conversion, Perforce contains the history of your software product viewable using the Revision Graph tool, and the history is similar to what would have been recorded if development was done using Perforce to begin with. Detailed data is discarded: you know what your product looked like at Release 1.0 and Release 2.0, for example, but hundreds of check-ins between those baselines are discarded, as are the user ID, date, time, and check-in comments.

Accurate diagrams are essential for planning a BBI migration. Ideally, release engineers can quickly draw an accurate branch history for each software product to be imported. If that is not the case, such information can be extracted by exploring ClearCase manually. After the diagram is drawn and verified, it is translated into the Perforce commands that re-create the baselines in Perforce. The first baseline is created by adding the entire product directory tree. Subsequent baselines are created using Perforce changelists that perform the changes (files added, deleted, or modified). Branching operations are translated into their Perforce equivalents. ClearCase merges are recorded as the results of the merges done in ClearCase.

If detailed historical research is needed often, keep ClearCase online (perhaps with a single license) for a year or two after a BBI migration.

Pros of a BBI Strategy

• Gives you the flexibility to do a multisystem migration of different teams on their own schedules without impacting others. Because the BBI approach works against a live, running Perforce Server (rather than generating separate Perforce Server instances like some detailed history import tools do), the project planning for the various teams does not require coordination. Each team can migrate to Perforce without impacting those already on Perforce.

• “Interesting history” is available in Perforce. After migrating, you can use Perforce’s powerful tools, such as Diff, Revision Graph, and Time-lapse View, to see your old files in a new light. Detailed history has been omitted, but you can tell how the software product evolved.

• The BBI process is fairly straightforward and has little risk of technical problems.

Delivered(Released)

MAINBranch

1.0 2.0 2.1 3.0 4.0

2.0 RelBranch

2.1 (new features)+ patch p1 merged

2.1 (new features)+ patch p2 merged

3.0 RelBranch

p1 p2 p3 p4 p1

Figure 1: Sample baseline and branch diagram.

Migration Planning Guide: IBM Rational ClearCase to Perforce7

branch was created may involve some guesswork, such as using /main/LATEST with a –time clause.

Terminology and ConceptsThe following sections map ClearCase concepts to their Perforce equivalents.

VOBs and DepotsA Perforce depot is roughly analogous to a ClearCase VOB (which stands for “versioned object base”). VOBs and depots both appear as top-level directories to users, and both store a set of files. One VOB or depot must exist before any file can be versioned.

A VOB is a container for versioned file contents and metadata relating to those versioned files. A Perforce depot contains only the contents of versioned files. All metadata is stored in a database on the Perforce server.

When mapping VOBs to depots, consider the following:

• Unlike files in VOBs, files in Perforce can be branched to other depots. VOBs in ClearCase are effectively islands of code.

• Perforce manages binary files efficiently, enabling you to manage all your digital assets. ClearCase sites avoid storing large number of binaries because of performance considerations. For example, a software product might consist of source code, software products built from that source code, and various released configurations of software products. A separate depot might be assigned for each, for example, //gizmo, //gizmo-build, and //gizmo-release.

• Perforce depot names should be kept short. //Engineering is OK, but //Eng is better.

//Eng-AdvancedTechnologyGroup is a bit long, so //Eng-ATG is better.

Regions and ProtectionsIn ClearCase, network registry regions are used to segregate VOBs. A region sees only a subset of all VOBs in a ClearCase installation.

To achieve similar segregation in Perforce, you use the protections table. Users are assigned to different Perforce groups. Access is then managed at the group level by assigning permissions to groups.

• You can load all of the historical information into Perforce prior to migrating. Then, on the day of the migration, only the baselines representing the latest active development branches need to be brought into Perforce because all historical information has already been imported.

• BBI runs very quickly, so dry runs can be done to test any source code changes required as part of the migration, such as updates to build scripts or makefiles.

• The amount of metadata resulting from BBI is negligible and does not affect server performance or require increased hardware.

• You can normalize history by creating branches in a consistent manner. Where branching strategies have evolved over time in ClearCase, you can simplify historical research of the imported baselines. With the BBI approach, you can restructure the depot to show how “software product X went to production” in the same way for each of the imported software products.

Cons of a BBI Strategy

• If files were renamed or directory structures were reorganized between releases, the historical connection between old and new file names is lost. For example, if a file foo.c in version 1.0 of your software product was renamed to bar.c in version 1.1, the rename is lost. ClearCase and Perforce track renames differently, so that information is lost by BBI migrations. BBI migrations can handle refactoring, though additional effort is required to identify refactoring events and layout baselines in such a way that from/to information is identified.

• ClearCase supports versioning of some uncommon, low-level file types that are not supported in Perforce, such as block special devices and character special devices. Such files cannot be imported, regardless of migration strategy. Symbolic links can be imported, however.

LimitationsIf software version management best practices were not followed, reproducing the baselines may be difficult in ClearCase.2 For example, if branches were made from /main/LATEST rather than from a label on MAIN, getting a config spec to represent the baseline from which a

2 Unfortunately, this is a common scenario with ClearCase.3 Deploying multiple Perforce Server instances within an enterprise is possible and common. For the purposes of this document, we consider only

the single-server-per-enterprise approach because that best suits most ClearCase migration scenarios.

Migration Planning Guide: IBM Rational ClearCase to Perforce 8

VOB Servers and the Perforce ServerIn ClearCase environments, you might have multiple VOB server processes, possibly distributed among multiple VOB server machines. With Perforce, a single Perforce Server can support an entire installation.3 The Perforce Server process, P4D, runs on a single machine, is frugal with system resources, and is much less demanding than ClearCase. One P4D process can scale to support extremely large environments (for example, 10,000+ users) on a single server using enterprise-grade server machines.

One of the first steps in any migration is to set up Perforce hardware. It is common to allocate two or three identical server machines to Perforce to achieve high availability and disaster recovery goals. A typical configuration is two servers (a primary and a hot spare) in a primary data center and a third server (warm spare) in another data center located far from the primary data center.

Operating System SelectionThe primary factor in selecting an operating platform for Perforce is the platform that the local IT group is most comfortable supporting. In mixed Windows/*nix environments, Unix platforms are almost invariably selected for ClearCase, because of case sensitivity reasons and because of its reliance on effectively monodirectional (Unix Ê Windows) file system mounts to make VOB data accessible to clients on both Unix and Windows.

You can configure the Perforce server on Windows or *nix in multiplatform environments. Only a TCP connection is needed between clients and servers. You can configure the case-sensitivity behavior of the Perforce Server independently of the platform.

Registry and License ServersPerforce does not require license or registry server processes or hardware to support it. A simple 0.5KB license file on the Perforce Server machine composes the entire Perforce license mechanism. For large environments with lots of turnover, Perforce provides alternative licensing schemes that supply extra licenses for growth.

Release Servers and InstallationWith ClearCase, to ensure users run client software that is compatible with the current version of the server, you

must manage server and client versions carefully. To aid in ensuring consistency, some ClearCase installations deploy a release server, which is a defined network resource from which all users are expected to download correct versions of client software. This approach provides a more scalable alternative to making sure everyone has the installation CD available.

With Perforce, all client components (and the server) install in minutes over the Web. More importantly, Perforce clients and the server have a very flexible forward- and backward-compatible relationship, because of a version-aware client/server protocol. Users can generally run client versions that are older or newer than the server. Client programs simply hide or disable features that require newer versions of the server, and new server versions rarely require client upgrades.

For Windows sites with a large number of users, Perforce supports a centrally configured, automated deployment of Perforce. You can use such sites to ensure that users download consistent, trusted versions of software that are supported by IT and/or release engineering staff. However, because of extreme compatibility and extreme ease of installation, maintaining such areas is much less of a requirement than in ClearCase environments.

View Servers, Protecting Unversioned and Checked-Out FilesPerforce stores all metadata in a database on the central server, managed by the P4D process.4 A ClearCase View Server process has no equivalent in Perforce, and administrators don’t need to allocate and configure View Server machines.

When dynamic views are used, View Server machines contain the contents of checked-out and unversioned-view private files. Some organizations back up view storage areas regularly to protect against the loss of such files. If protecting checked-out and unversioned files is a priority, you will need to back up client machines. However, P4Sandbox provides a local repository and other features to the end user, and can be used to version work-in-progress or work that is not intended to be shared.

Some organizations devise a process to protect unversioned and checked-out workspace files in Perforce, such as locating workspaces on network drives that are backed up. During Perforce training, users are advised to avoid keeping files checked out for too long, using sandbox branches or P4Sandbox if needed.

4 Some GUI programs temporarily cache metadata in running processes, but such information is not persisted.

Migration Planning Guide: IBM Rational ClearCase to Perforce9

ClearCase MultiSite versus Perforce ProxiesIf your ClearCase environment relies on MultiSite, you will find the Perforce Proxy mechanism is simple and effective. Perforce proxies cache the contents of versioned files at remote sites, greatly reducing dependency on the WAN.

Proxies do not cache any metadata, thereby ensuring that there is a single source of state information and eliminating the need for branch mastership, scheduling batch replication, and so on. Once hardware is available, proxy servers can be setup in minutes and require virtually no maintenance.

Perforce replica servers provide read-only access to all data (file content and metadata). Perforce replicas are more capable than proxy servers and have a small administrative footprint. Perforce replicas provide improved performance for remote teams and automated processes like continuous integration builds, as all read-only data is serviced locally. Data consistency is maintained because there is still one canonical representation of important data on the central server

Replicated VOB servers generally run on server machines that are similar to the primary server, thus requiring similar-tiered data centers. Because of the significant investment in licenses, hardware, and administrative overhead, MultiSite installations are used only where major development centers exist, and they are of little use to small, geographically diverse teams.

By contrast, Perforce Proxy servers are lightweight programs that can run on desktop-grade hardware, even in enterprise environments. Proxy servers do not require high-performance hardware or large amounts of disk space, so they can be deployed anywhere that a few developers gather. In some cases, individual users deploy Perforce Proxy instances in small offices without IT support.

Perforce replicas require more powerful hardware than a proxy server, but have a small administrative footprint and are useful for small or medium sized teams as well as larger sites. There are no additional costs or licenses required to deploy a Perforce Proxy or replica server.

ClearCase Views with Perforce WorkspacesThe term “workspace” is familiar to both ClearCase and Perforce users: it is where developers manage files under version control on their local machines.

With ClearCase, it is typical for a developer to maintain several workspaces, called “views.” Developers who are working on multiple branches typically use a different view for each activity, working in one view at a time. For example, a developer might maintain a joe_user_main_dev view with a config spec selecting /main/LATEST versions and a separate joe_user_rel_2.3 view selecting /main/REL2.3/LATEST versions.5

A Perforce “client specification” defines a workspace and determines the files from the server that are visible in the workspace. Branches in Perforce appear to the user as fully-populated directory trees. For example, the server might contain a directory named MAIN and another directory named REL2.3. A developer might have a joe_user_dev workspace, that includes both MAIN and REL2.3 directories. The developer can work in both activities at the same time.

Perforce Streams provide some capability to specify which modules are actively in use in a branch and import dependencies from other projects.

In Perforce, only user files are stored on the local disk. All metadata, including information about the name and contents of a user’s workspace, resides on the server.

Label StrategiesBoth ClearCase and Perforce provide labels, which identify the versions of files that constitute a baseline. For many ClearCase users, labels are mandatory. Applying labels is time-consuming, often accounting for 30 percent or more of the time associated with creating stable builds.

In Perforce, labels are just one way of reproducing baselines. Changelists accomplish the same goal in ways that are less taxing on the build process and faster and easier to reference than a label.

Each Perforce check-in generates a unique changelist number that reflects the state of the repository at a point in time. Any changelist can be used to describe the state of every file in the repository, even though it affects only a small subset of the repository.

5 This is an oversimplication since a typical config spec is several lines or more.

Migration Planning Guide: IBM Rational ClearCase to Perforce 10

Branches in Perforce are represented as directories, making it easy to combine branches and changelist numbers to represent a baseline. Alternately, labels can refer to changelist numbers limited to an identified scope in the server, where the scope is typically a particular branch.

Unified Change Management (UCM)UCM adds a layer of process to ClearCase. UCM also provides guidance on common software promotion models and branching strategies.

Out of the box, Perforce provides atomic changelists and jobs, which correlate to UCM functionality that enables ClearCase developers to group files and connect them to an activity description. Perforce Streams provide flexible workflow and guidance for release management and, when used in conjunction with other ALM tools, can largely replace ClearCase UCM.

Migration Technical DetailsPerforce and ClearCase have very different internal representations and models of parallel development, branching, and merging. Both support parallel development, but you should be aware of the differences.

Evil TwinsDescribes the problem in which two elements with the same name appear in different branches. For example, say you have a MAIN, DEV_A, and DEV_B branches, with each of the DEV branches parented directly from MAIN. In DEV_A branch, a developer does a ‘ct mkelem’ to create a new file element, foo.c. Independently in DEV_B branch, a developer does the same thing —does a ‘ct mkelem’ to create a new file element, foo.c. Someone then does a ‘ct findmerge’ to make file that originated on DEV_A appear on MAIN. Later, someone does another ‘ct findmerge’ intending to merge changes from MAIN to DEV_B, including the new foo.c merged to MAIN earlier from DEV_A.

Which is the real “foo.c” in DEV_B, the one that originated in DEV_A, or the one that originated in but not obvious to most users. ClearCase provides no warning about this problem. Situations are even worse when there are evil twin directories.

This is one of the more insidious complexities of ClearCase. ClearCase admins aware of this potentially

confusing scenario sometimes put in “Evil Twin Detection” and “Evil Twin Prevention” triggers. When migrating data from ClearCase, evil twins are murky history that should not (and cannot) be migrated into Perforce. We detect instances of evil twins, manually select the correct element from the pair, and use ‘ct rmelem’ to eliminate the evil twin.

In Perforce, the same filename can be created independently in two branches. However, Perforce enables you to resolve the situation the first time you merge the branches together. The file histories can be combined, instead of having to kill off an evil twin and lose its history.

Symlinks on WindowsThrough use of Multi-Version File System (MVFS), ClearCase supports symlinks on Windows in dynamic views. Perforce does not have a custom filesystem and does not support symlinks on platforms that do not natively support it. Symlinks are supported on Windows Vista, 7, and Server 2008, but not on earlier versions of Windows. If you use symlinks on earlier versions of Windows, you must decide how to handle them when planning a migration.

Perforce allows symlinks to be versioned. When a file of type ‘symlink’ is brought into a Perforce workspace on a Windows machine without symlink support, it appears as a text file containing the path of the target file. For example, using a Linux workspace, you issue the ‘ln –s hello.hpp hello.h’ and the file hello.h is a symlink pointing to hellol.hpp. In Perforce, if you sync the hello.h symlink to a Windows workspace without symlink support, you get a file with the contents being “hello.hpp”, the path to the target of the symlink. You do not get the content of the target file, as you do in a ClearCase snapshot view.

File Type Mappings and LimitationsWhen migrating from ClearCase to Perforce, the Perforce typemap feature, which assigns file types based on Perforce pathname heuristics, enables you to ensure that files are added correctly. This capability is especially important for Unicode files.

ClearCase permits versioning of some special filesystem objects, such as block special devices, character special devices, and hard links. These objects have no equivalent in Perforce. If such objects are versioned in ClearCase, you will need to account for that in your migration planning.

Migration Planning Guide: IBM Rational ClearCase to Perforce11

Learn MoreUse these resources to help plan your ClearCase to Perforce migration.

Perforce Knowledge Base Articles

• Read KB article, General Perforce Recommendations, for information useful in capacity planning for your primary server.

• Read KB article, Automated Deployment of Perforce, for more details about supporting Windows installations for enterprise-sized sites.

Perforce Directory Standard Template

• Download the PDS template for developing your own Perforce Directory Standard.

• Participate in discussions about the PDS on the Perforce Forums

Branching Strategies and Best Practices Implementation

• Read Perforce VP of Technology Laura Wingerd’s book, “Practical Perforce” (2006, O’Reilly).

• Watch “The Flow of Change” (56 mins.) a Google Tech Talk in which Laura Wingerd discusses modeling the flow of change in Perforce.

Perforce ComparisonsPerforce comparisons including “Perforce and IBM Rational ClearCase” are available at perforce.com/comparisons

Perforce Consulting ServicesPerforce Consulting can help you identify the risks and challenges involved for your particular environment, and assist you at every step of the migration process. If you need help capturing and documenting migration requirements, establishing a high-level project plan and migration schedule, or need cost of effort estimates for implementation, visit: perforce.com/consulting

Migration Planning Guide: IBM Rational ClearCase to Perforce 12

Migration Planning ChecklistClearCase environments vary widely in terms of size, complexity, geographic distribution, and integration with other systems. Common reasons for replacing ClearCase with Perforce include:

• Reducing operational costs.• Simplifiying access for users and distributed teams.• Expanding capabilities.• Desire for a faster software version management system.

Use this checklist to help you plan your migration from ClearCase to Perforce.

R Define your migration requirements: Consider the amount of history that must be available in Perforce after the migration.

R Select a data conversion strategy: For each VOB, decide whether to import all history, selected history, or only the most recent revisions.

R Evaluate ClearCase usage: Determine what features are in use (labels, etc.) and decide how to implement them in Perforce. Check for structural corruption (such as “evil twin” files).

R Consider user interactions: Define the various users and groups that interact with ClearCase and assess the impact a migration will have on each one.

R Evaluate tools, processes, and infrastructure: In Perforce, you might decide to replace certain ClearCase functionality, change implementations, or abandon unneeded components. Examples of tools, processes, and infrastructure that might have been built around or integrated with ClearCase include: build systems, branching strategies, continuous integration frameworks, procedures for defining a release (labeling, branching, etc.); ClearCase UCM, MultiSite or clearmake, software version management policies and policy enforcement mechanisms (triggers, scripts, review daemons).

R Develop a Perforce Directory Standard (PDS): To promote best practices for configuration management throughout the product lifecycle and intuitively convey key aspects of the release process and the lifecycle stage of any given file or software change.

North America Perforce_Software_Inc.2320_Blanding_AveAlameda,_CA_94501USAPhone:_+1_510.864.7400info@perforce.com

EuropePerforce_Software_UK_Ltd._West_Forest_GateWellington_RoadWokinghamBerkshire_RG40_2ATUKPhone:_+44_(0)_845_345_0116uk@perforce.com

Australia Perforce_Software_Pty._Ltd.Suite_3,_Level_10221_Miller_StreetNorth_SydneyNSW_2060AUSTRALIAPhone:_+61_(0)2_8912-4600au@perforce.com

Copyright © 2012 Perforce Software Inc. All rights reserved. All trademarks or registered trademarks used herein are property of their respective owners.

p e r f o r c e . c o m