Migration Planning Guide: IBM Rational ClearCase to Perforce by Daniel Liezrowice

Migration Planning Guide: IBM Rational ClearCase to Perforce SCM

Perforce ClearCase to

Table of Contents 1. Introduction ____________________________________________________________________________ 3 2. Preliminary Migration Preparation _______________________________________________________ 3 Reviewing Existing Branching Strategy _____________________________________________________ 3 Planning the Directory Structure ___________________________________________________________ 3 Defining Release Processes and Directory Structure Standards ________________________________ 3 Addressing Intellectual Property Concerns __________________________________________________ 4 Training _______________________________________________________________________________ 4 Transition Team _________________________________________________________________________ 4 3. Import Strategies _______________________________________________________________________ 4 Starting Over (Tips) _____________________________________________________________________ 5 Pros ______________________________________________________________________________ 5 Cons _____________________________________________________________________________ 5 Detailed History Import (DHI) _____________________________________________________________ 5 Preparation for a ClearCase Detailed History Import ______________________________________ 6 Extracting and Importing _____________________________________________________________ 6 Custom Scripting ___________________________________________________________________ 7 Hardware Capacity Planning _________________________________________________________ 7 Pros _________________________________________________________________________ 7 Cons ________________________________________________________________________ 7 Baseline and Branch Import (BBI) _________________________________________________________ 7 Pros______________________________________________________________________________ 9 Cons _____________________________________________________________________________ 9 Limitations ________________________________________________________________________ 9 4. Terminology and Concepts _____________________________________________________________ 10 VOBs and Depots _____________________________________________________________________ 10 Regions and Protections ________________________________________________________________ 10 VOB Servers and the Perforce Server _____________________________________________________ 10 Operating System Selection _________________________________________________________ 10 Registry and License Servers ____________________________________________________________ 11 Release Servers and Installation __________________________________________________________ 11 View Servers, Protecting Unversioned and Checked-Out Files _________________________________ 11 ClearCase MultiSite versus Perforce Proxies _______________________________________________ 11 ClearCase Views with Perforce Workspaces _______________________________________________ 12 Label Strategies _______________________________________________________________________ 12 Unified Change Management (UCM) ______________________________________________________ 13 Migration Technical Details ______________________________________________________________ 13 Evil Twins _________________________________________________________________________ 13 Symlinks on Windows ______________________________________________________________ 13 File Type Mappings and Limitations ___________________________________________________ 14 5. Additional Resources __________________________________________________________________ 14 6. Migration Planning Checklist ___________________________________________________________ 15

1. Introduction This document tells you how to plan to migrate from legacy ClearCase to Perforce SCM 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, please visit perforce.com/consulting.

2. Preliminary Migration Preparation The following factors inform a migration strategy from ClearCase to Perforce.

Reviewing Existing Branching Strategy

Early 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 Structure

With Perforceâ&#x20AC;&#x2122;s Inter-File Branchingâ&#x201E;˘ mechanism, the directory structure and branch model are related. 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 Standards

Think 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.

Addressing Intellectual Property Concerns

Knowing where your source code came from and knowing what legal rights you have to it can be a priority when migrating to a new SCM 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. SCM 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.

Training

To 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. See Training in Additional Resources for more information.

Transition Team

We 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.

3. Import Strategies There 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.

Migration Planning Guide: IBM Rational ClearCase to Perforce SCM

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.

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 Import This 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 SCM 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 Import

If 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. • 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.

Migration Planning Guide: IBM Rational ClearCase to Perforce SCM

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 Scripting

A detailed migration sometimes involves custom scripting due to differences in ClearCase usage and any oddities in a particular data set.

Hardware Capacity Planning

Hardware capacity planning may be impacted significantly with DHI migrations. An SCM 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 history import tools have a variety of limitations and technical caveats because of the potential complexity of ClearCase environments, including unusual patterns (or even corruption) in the data. So-called evil-twin elements or branching scenarios created by misconfigured config specs can be difficult to follow. • Complex migrations can mean 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 SCM systems, including IBM Rational ClearCase, Borland StarTeam, Merant PVCS, 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.

Subversion, Mercurial, CVS, Microsoft Visual Source Safe, AccuRev, and even unsophisticated SCM “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 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. Delivered (Released)

MAIN Branch

1.0

2.0

2.1

2.1 (new features) + patch p1 merged

2.0 Rel Branch

3.0

3.0 Rel Branch

4.0

2.1 (new features) + patch p2 merged

Figure 1: Sample baseline and branch diagram 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

Migration Planning Guide: IBM Rational ClearCase to Perforce SCM

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. • 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.

Limitations If SCM 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 branch was created may involve some guesswork, such as using /main/LATEST with a –time clause. 2. Unfortunately, this is a common scenario with ClearCase.

4. Terminology and Concepts The following sections map ClearCase concepts to their Perforce equivalents.

VOBs and Depots

A 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 Protections

In 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.

VOB Servers and the Perforce Server

In 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 Selection The 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 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 SCM

effectively monodirectional (Unix Ă&#x160; 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 Servers

Perforce 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 Installation

With 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 Files

Perforce 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â&#x20AC;&#x2122;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. 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 if needed.

ClearCase MultiSite versus Perforce Proxies

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

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

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. 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. There are no additional costs or licenses required to deploy a Perforce Proxy server.

ClearCase Views with Perforce Workspaces

The 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. 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 Strategies

Both 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. 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.

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

Migration Planning Guide: IBM Rational ClearCase to Perforce SCM

Unified Change Management (UCM)

UCM adds a layer of process to ClearCase. 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. UCM also provides guidance on common software promotion models and branching strategies. Perforce’s open architecture accommodates various enterprise-wide development methodologies and SCM customizations.

Migration Technical Details

Perforce 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 Twins Describes 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 DEV_B? It’s not clear. One is identified as the correct file, and the other is the evil twin. One might expect them to be branch-relations of the same element, but they’re not related in the ClearCase database. As far as ClearCase is concerned, they’re completely independent elements, referenced in its database by different OIDs (object identifiers). The findmerge completes successfully, and you would have two foo.c’s in the branch, but the operating system permits only one foo.c to appear in the directory. The one that shows in your view is deterministic, 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 Windows Through 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. If you use symlinks on 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, 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,

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 Limitations When 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.

5. Additional Resources Use 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.

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.

SCM Comparisons

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

Training

We offer instructor-led online and classroom training, as well as on-site and custom training. See perforce.com/training for more information.

Migration Planning Guide: IBM Rational ClearCase to Perforce SCM

6. Migration Planning Checklist ClearCase 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 SCM system. Use this checklist to help you plan your migration from ClearCase to Perforce. 55 Define your migration requirements: Consider the amount of history that must be available in Perforce after the migration. 55 Select a data conversion strategy: For each VOB, decide whether to import all history, selected history, or only the most recent revisions. 55 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). 55 Consider user interactions: Define the various users and groups that interact with ClearCase and assess the impact a migration will have on each one. 55 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, SCM policies and policy enforcement mechanisms (triggers, scripts, review daemons). 55 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.

About Perforce Consulting Perforce 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, please visit: perforce.com/consulting.