IBM Rational Clearcase to Perforce VCS Migration Guide

MIGRATION GUIDE

IBM Rational ClearCase to Perforce VCS Migration Guide

v2.5, January 31, 2017 This document provides information for planning a migration from a legacy ClearCase VCS system to Perforce VCS. Basic familiarity with ClearCase architecture, concepts, and terminology are helpful, but not strictly necessary, when reading this document. Corresponding Perforce concepts and terminology are introduced.

We discuss preliminary planning and review three history import strategies – starting over, detailed history import (DHI), and baseline & 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 Perforce setup, migration, and training for users and administrators. Large, complex ClearCase environments may perform a series of migrations that occur over the course of a several months or more, as teams migrate at times convenient for them.

This document is not intended to be a replacement for an actual assessment of your environment. An assessment would focus on those factors most relevant to your environment and produce a custom migration strategy. MIGRATION GUIDE IBM Rational ClearCase to Perforce SCM Migration Guide | ii

1. Introduction...... 1 2. Preliminary Migration Preparation...... 1 2.1. Review Existing Branching Strategy...... 1 2.2. Perforce Directory Standard (PDS)...... 1 2.3. Release Processes and the PDS...... 1 2.4. Perforce Streams...... 2 2.5. Addressing Intellectual Property Concerns...... 2 2.6. Training...... 2 2.7. Perforce Transition Team...... 2 3. Import Strategies...... 3 3.1. Tips – Starting Over...... 3 3.1.1. Starting Over – Pros...... 3 3.1.2. Starting Over – Cons...... 3 3.2. Detailed History Import...... 3 3.2.1. ClearCase Detailed Import History Preparation...... 4 3.2.2. Custom Scripting...... 4 3.2.3. Hardware Capacity Planning...... 4 3.2.4. Detailed History Import – Pros...... 4 3.2.5. Detailed History Import – Cons...... 5 3.3. Baseline & Branch Import...... 5 3.3.1. Baseline & Branch Import – Pros...... 6 3.3.2. Baseline & Branch Import – Cons...... 7 3.3.3. Warnings...... 7 4. Terminology and Concepts...... 7 4.1. VOBs and Depots...... 7 4.2. ClearCase Regions...... 7 4.3. VOB Servers vs. “The Server”...... 8 4.3.1. Operating System Selection...... 8 4.4. Registry and License Servers...... 8 4.5. Release Servers and Installation...... 8 4.6. View Servers, Protecting Unversioned and Checked Out Files...... 9 4.7. ClearCase MultiSite vs. Perforce Proxies...... 9 4.8. Replacing ClearCase Views with Perforce Workspaces...... 9 4.9. Rethink Label Strategies...... 10 4.10. Unified Change Management (UCM)...... 10 4.11. Migration Technical Details...... 10 4.11.1. Evil Twins...... 10 4.11.2. Symlinks on Windows...... 11 4.11.3. File Type Mappings and Limitations...... 11

Perforce Software 400 N. 1st Avenue, Suite 200 +1 510.864.7400 www.perforce.com Minneapolis, MN 55401 [email protected] Copyright © 2008-2017, Perforce Software. All rights reserved. MIGRATION GUIDE IBM Rational ClearCase to Perforce SCM Migration Guide | 1

• Helps convey branching patterns for 1. Introduction everything Perforce. This document provides information for planning a • Helps intuitively map change propagation paths for the migration from a legacy ClearCase VCS system to Perforce various flows of change (e.g. the life of a bug discovered VCS. Basic familiarity with ClearCase architecture, in maintenance, or the life of a new feature). concepts, and terminology are helpful, but not strictly • Conveys the stage in the life cycle of any particular necessary, when reading this document. Corresponding piece of code: experimental, development, released. Perforce concepts and terminology are introduced. It is a best practice to establish a Perforce Directory Standard We discuss preliminary planning and review three history (PDS) to establish the directory structure and corresponding import strategies – starting over, detailed history import branching strategy in Perforce. A template for developing (DHI), and baseline & branch import (BBI). your own PDS is available for download here. You can participate in discussions about the PDS on the Perforce ClearCase to Perforce migration projects vary greatly in scale Forums here. Contact Perforce Consulting and complexity. Small, simple environments with basic ([email protected]) for further information. migration requirements are typically migrated in about eight business days, including Perforce setup, migration, 2.3. Release Processes and the PDS and training for users and administrators. Large, complex The directory structure in Perforce can be thought of as ClearCase environments may perform a series of migrations “low” and “high” levels. Low levels represent your software that occur over the course of a several months or more, as products, and can vary for each software product. High teams migrate at times convenient for them. levels of a Perforce directory structure convey branching structure, project management, and software lifecycle This document is not intended to be a replacement for an information. A well-designed, high-level directory structure actual assessment of your environment. An assessment is intuitive for developers and lends itself well to project would focus on those factors most relevant to your management metrics, policy enforcement by branch type, environment and produce a custom migration strategy. and automation of various kinds.

Migration to Perforce typically involves defining a Perforce 2. Preliminary Migration Preparation Directory Standard (PDS) for each product imported into Perforce, and in some cases for the entire organization. A 2.1. Review Existing Branching Strategy Early in migration planning, determine whether the current PDS encourages consistency in release processes for various branching strategy used in ClearCase, if any, is appropriate software products, but can be as flexible as needed to to use going forward with Perforce. If not, tweak the strategy account for the different release processes and branching as needed first. Creating an initial branching strategy is a patterns associated with various software products best practice when getting started in Perforce in any case. in Perforce. Perforce Streams can model the branching strategy and For example, one software product might be a licensed intended flow of change. software product, the release process for which would define how to maintain old releases and deliver patches. 2.2. Perforce Directory Standard (PDS) With the Inter-File™ branching mechanism in Perforce, A web-based software product operated in your own data the directory structure and branching strategy are related. center would follow a different release process, in which A well-designed directory structure in Perforce is critical, there is little need to maintain old releases, but which must because it: support 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 may also Migrations provide an opportunity review access control vary due to the number of contributors and the degree of policies. In some cases, ensuring strong IP protections structure of QA processes. Software products can follow requires extra effort, causing people to wonder if strong the same release process, even though they might have very access controls really benefit the organization. In other cases, different releaseschedules . migrations expose particularly weak access controls, and powerful and flexible access control capabilities in Helix The low levels of the directory structure are left untouched Versioning Engine provide a straightforward means of by the migration, to minimize the difficulty of performing guarding IP with relative ease. the migration and minimize the impact of the migration to your environment (e.g. build scripts, release processes and 2.6. Training tools, etc.). Training for Perforce users and administrators is essential to help a migration go smoothly, and to help get the most from 2.4. Perforce Streams Perforce after the migration. With respect to scheduling, Perforce streams model branches at a higher level. A stream we find it most effective if training for the bulk of Perforce defines a set of related files, where those files came from (the users occurs between a few days and a few weeks prior to the parent stream), how change flows to other streams, and how cutover to Perforce. parts of a stream are treated in the workspace. Perforce provides a variety of training options including Streams are an attractive framework for new projects in-person and online instructor-led training. An effective in Perforce. The tools and workflow improvements strategy is to provide instructor-led training to a core set of simplify work for end users and make project and release administrators and key users (“train the trainers”), who then management easier. train the bulk of users. The Detailed History Import tool used by Perforce does 2.7. Perforce Transition Team not currently allow ClearCase data to be imported directly We recommend establishing a transition team. This core as streams. However, ClearCase data can be imported into group may include application administrators, system regular Perforce branches and then migrated to streams for administrators, and other influential users. You might future work. Alternatively, the Baseline & Branch Import consider engaging Perforce Consulting to participate in your method can be used to import ClearCase data directly transition team. into streams. The transition team defines how Perforce will be used in 2.5. Addressing Intellectual Property Concerns your organization, how it will tie into your various Maintaining IP provenance (i.e., knowing where your source processes and workflows, and how it will be integrated with code came from, knowing what legal rights you have to other systems. it) can be a priority in VCS migration scenarios. From the perspective of a migration process, your goal should be to For larger and more complex migrations, training for this ensure that IP provenance is not negatively affected by the team should occur early in the planning process. This migration. Your migration processes should provide a clear allows best practices established by the team to evolve, be audit trail so that all imported files can be traced back to the documented and proliferated during the training for the original ClearCase repository. larger user community, which occurs later in the migration process. VCS systems inherently store valuable intellectual property. If sensitive information is being migrated, both the migration process and the resulting Perforce environment should ensure that access is controlled to the same degree as it was in ClearCase.

branches, as that requires knowing the historical 3. Import Strategies relationship among the branches. We discuss three approaches for importing files: starting 3.2. Detailed History Import over (“Tips”), detailed history import (DHI), which can This is the logical extreme case of conversion. The goal with be exhaustive or selective, and baseline & branch import this approach is to capture as much detailed branch/merge (BBI) strategy, which is inherently selective. Following is an information as practical, so that comprehensive historical overview of the strengths and limitations of each research can be done in the new system, without benefit of import strategy. the old.

3.1. Tips – Starting Over Published, supported tools exist to import from CVS, RCS, This isn't really a conversion strategy. This approach is VSS, and Subversion. Perforce Software currently has a to get the “tips” — the /main/LATEST file versions from sophisticated tool and process that enables conversion of ClearCase, and simply add them to Perforce, without any very detailed historical data from ClearCase to Perforce. history at all. The tool has been successfully used for performing detailed Based on the organization’s Perforce Directory Standard, a history conversions from fairly large ClearCase data sets high-level directory is identified in which the files will be (about 100 GB) to Perforce. Due to licensing restrictions stored, perhaps something like: and operational complexity, the ClearCase DHI conversion tool is presently available only by engaging Perforce //Gizmo/main/src Consulting services.

Here, Gizmo is a product name, main indicates files in the Detailed history migrations from ClearCase can be selective. main stream of development, and src is the root of the low- A subset of VOBs can be imported. Within each imported level directory tree. The low-level directory tree is copied VOB, a subset of all available files and labels are typically verbatim into Perforce. targeted for import. Conversion includes file contents at each revision, the userid/date/time/checkin comment The Tips approach is sometimes appropriate for things associated with each checkin, file renames, and detailed like documentation VOBs, or VOBs for shelved (but not branching and merging history. ClearCase’s representation terminated) projects. It is usually not appropriate for source of branching activity is translated into Perforce code, except for prototype and demo code. “integration records.” Even in simple Tips migrations, care must be taken to The import process uses heuristics to group ClearCase ensure that file types are mapped correctly. Text, binary, “checkins” into Perforce “changelists.” For example, if a and Unicode files should be mapped correctly, and file type given user checked in a set of files at the same time (+/- a modifiers are applied, such as ‘+x’ for executables, ‘+F’ for few minutes) with the same checkin comment, those will compressed binary formats like *.gz or *.mpg, etc. be grouped together as a single Perforce changelist. UCM 3.1.1. Starting Over – Pros metadata, if available, also factors into changelist grouping. • It is easy. You need only define target directories in Our migration process starts by scanning repositories for Perforce, and then add the files. various issues that need to be resolved in ClearCase or • It is fast. otherwise handled manually prior migration. Examples of things that must be resolved prior to migration include: 3.1.2. Starting Over – Cons • No historical information is available in Perforce. • “Evil twin” files and directories. • If multiple branches are imported, Perforce won’t • File types such as “block special devices” that are be able to simplify first-time merges between the supported only in ClearCase.

• File types such as hard links that can be imported, but are Windows. A fast network connection between the require special emulation in Perforce. ClearCase replica machine, the migration server, and • Architectural and conceptual differences between the Perforce server (which can be the same machine) ClearCase and Perforce. For example, mapping is essential. ClearCase labels to Perforce proves rather difficult, • Migration is a very resource-intensive process, and can because typical usage of labels varies between the potentially be very demanding in terms of disk space systems, as well as the underlying implementations. and RAM resources. It is more demanding than actual • Certain rare “circular merge” activities don’t translate server Perforce operation, as years of work done in into Perforce well. ClearCase is compressed into hours or days. • ClearCase repositories tend to have mild data corruption that might not be visible to normal users, 3.2.2. Custom Scripting but would be exposed when running the sorts of A detailed migration often involves custom scripting due commands that a detailed conversion history tool to differences in ClearCase usage, oddities in any particular must use. data set, and custom requirements.

Detailed history migration is a more involved undertaking 3.2.3. Hardware Capacity Planning with ClearCase than with other VCS systems. Concepts Hardware capacity planning may be impacted significantly from UCM and RUP that depend on ClearCase attributes, with DHI migrations. Any VCS system with 12 years of triggers, and the like are not handled by import tools, history could be expected to require more hardware (more and require manual porting. Depending on the amount disk space, more RAM, faster CPUs and I/O subsystems, of data being migrated and the speed of ClearCase in etc.) than one with no history. If a detailed import of 12 your environment, a complex migration strategy using years of history is performed, the brand new Perforce system imports running in parallel may be required. Extracting all will have 12 years of history, and will initially require as information from ClearCase in a typical ClearCase setup much hardware as if it had it been in operation for 12 years. with years of history might take a full week to perform the 3.2.4. Detailed History Import – Pros mechanical extraction/import, limited mainly by the speed • Detailed history imports discover ClearCase history of ClearCase. and import significant historical detail into Perforce, including branching history. 3.2.1. ClearCase Detailed • After the migration, comprehensive historical research Import History Preparation If you plan to engage Perforce to help you plan a detailed and “merge forensics” can be done in Perforce without history migration from ClearCase, here are a few things to the need for going back to ClearCase. That said, we be aware of early in your planning process: recommend keeping ClearCase around with 1 user license, as a backup, if possible. • You’ll need to establish a replica of your ClearCase • The ability to view file history with Perforce’s powerful environment, including all VOBs targeted for import, visualization tools like Time Lapse View can shed new should be provisioned on hardware separate from light on the evolution of source code, and help increase your production environment. This allows dry runs understanding of the changes over time. and other data analysis that can be unduly taxing on a • There is increased benefit for systems integrated with production server. version control. For example, the meaning of the • A powerful, dedicated migration server machine linkage between a set of files originally modified in must be available. This can be the new Perforce server ClearCase and an issue from your issue tracking system machine, but does not need to be. This must be a can be maintained. Code review tools such as Perforce Linux server, even if the production and replica servers Swarm have greater context.

• Unlike Perforce, ClearCase does not have a way to Sample Baseline & Branch Diagram validate the integrity of versioned file contents using checksums. Corruption of file contents, e.g. due to Delivered (Released) disk failures, can go undetected1. Once historical data p1 p2 p3 p4 p1 2.0-Rel 3.0-Rel is in Perforce, it will gain the benefit of checksum Branch Branch verification of contents of all revisions, improving IP provenance. 1.0 2.0 2.1 3.0 4.0 3.2.5. Detailed History Import – Cons Delivered (Released) 2.1 (new features) + patch p1 merged • Detailed import tools have a variety of limitations 2.1 (new features) + and technical caveats. Some limitations are due to patch p2 merged differences in the way ClearCase and Perforce work, Figure 1: Sample Baseline & Branch Diagram and some are due to the potential complexity of The baselines (blue dots) indicate what “interesting ClearCase environments, including unusual patterns versions” are to be imported. The arrows indicate major (or even corruption) in the data. So called “Evil Twin” branching operations – that is, branching operations that elements and certain circular branching patterns affect an entire branch. In this scenario, a 2.0-Rel branch has created by misconfigured config specs can be difficult been created, and four patches were created on that branch. to follow. As of the time of cutover to Perforce, only two of those four • Existing detailed history import tools may require patches have been merged back to MAIN. The BBI process development to work on your data. The likelihood of imports all the baselines, records the fact that the merges this depends on your data, and is typically necessary if of two patches were completed with resulting updates to a full-context migration is attempted. MAIN, and tracks the two unmerged patches remaining on • Complexity translates into potential schedule and the release branch. Once in Perforce, Perforce can be used to budget risks for the migration project. complete those merges.

3.3. Baseline & Branch Import Importing the branching operations allows Perforce to The baselines & branch import (BBI) strategy provides a select common ancestors when doing merge work, thus lightweight migration alternative that is more sophisticated allowing Perforce to pick up where you left off with than the simple Tips approach, yet without the technical branching activities, after the cutover to Perforce. The complexity involved in detailed history imports. BBI process imports branching operations at a high level, The baseline & branch import process is a generic from- capturing the sum of merge operations. For example, in anything-to-Perforce process, and has been used to migrate the diagram above, the arrow representing the merge of to Perforce from a variety of VCS systems, including IBM p2 back to MAIN would likely have occurred as a series of Rational ClearCase®, Borland StarTeam®, Merant PVCS®, merges carried out by several developers. The individual Subversion, Mercurial, CVS, Microsoft Visual Source Safe, file merges are not tracked, but the sum of the results of the AccuRev, and even unsophisticated VCS “systems” like a set merge (file adds, edits, and deletes) is tracked. The imported of network drives with directories named to baseline represents a point in time when the merge of p2 is indicate releases. considered complete.

With the BBI approach, the “interesting history” to be imported is described in the form of a branch diagram that 1ClearCase does have a ‘checkvob’ utility that can detect and shows the baselines (snapshots of a directory structure at a fix some forms of metadata corruption. However, this utility point in time) and major branching operations. For example, does not detect data container corruption, and thus the a diagram like the following might represent the history of a contents of versioned files cannot be audited. software product:

The intent is to bring over just enough branching history to going to Perforce on their own schedule and without answer key questions, like “What did Release 2.0 look like?”, impacting others. Because the BBI approach works “Where was this file branched from?”, and “What files do I against a live, running Perforce server (rather than need in my workspace to start maintenance work on Release generating separate Perforce server instances like some 2.3?” The BBI approach preserves file contents at key points, detailed history import tools), the project planning for and preserves enough branching history so that cutover to the various teams does not require coordination. Each Perforce can happen at any point in the release cycle, rather team can migrate to Perforce without impacting those than just at “convenient” points in the schedule (which tend already on Perforce. to be hard to find). • “Interesting” history is available in Perforce. Once in Perforce, you can use Perforce’s powerful file and Thus, after conversion, Perforce would show history of directory diff tools, the Revision Graph, and Time your software product in its Revision Graph tool that Lapse view to see your old files in a new light. Unlike would essentially be similar to what would be shown had the detailed imports, you won’t be able to tell exactly development occurred in Perforce to begin with. Detailed who changed what, when, and why. But you can tell data is lost — you will know what the state of your product how the software product evolved from baseline to looked like at Release 1.0 and Release 2.0, for example, but baseline. hundreds of checkins between those baselines are discarded, • The BBI process is fairly straightforward, and has little as are the userid, date, time, and checkin comments. risk of technical snags. Accurate diagrams are essential for planning a BBI • Compared to detailed options, this approach makes migration. Ideally, release engineers can quickly draw a migration particularly easy, because all the historical branch history picture that they know to be accurate for information can be loaded into Perforce at any point in each software product to be imported. If that is not the case, time prior to cutover. Then, on the day of cutover, only such information can be extracted by exploring ClearCase the baselines representing latest state of development manually. Once the diagram is drawn and vetted by key on active branches need to be brought into Perforce, as people, it is translated into a set of Perforce commands that all historical information would already be imported. recreate the baselines in Perforce. The first baseline will • BBI runs very quickly, so throw-away dry runs can appear as an initial addition of the entire product directory be done in order to develop and test any source code tree. Subsequent baselines result in Perforce changelists changes that may need to be done as part of the that show only the changes (files added, deleted, or migration, such as updates to build scripts or makefiles. modified). Branching operations are translated into Perforce • The amount of metadata resulting from BBI is equivalents. Merges done in ClearCase are recorded in such negligible, and does not unduly impact performance or a way that Perforce honors the results of the merges done in initial capacity planning. ClearCase. • You have the opportunity to normalize past history into a new PDS, which indicates activities such as If detailed historical research is often needed, ClearCase can creation of branches in a consistent manner. In cases be kept online (perhaps with a single license). It is a good where branching strategies evolved over time with idea to keep ClearCase around for a year or two after a ClearCase, this provides a chance to simplify historical BBI migration. research of the imported baselines. With the BBI approach, it can be made so that common concepts 3.3.1. Baseline & Branch Import – Pros such as “software product X went to production” can • Ideally, it is nice to have the flexibility to do a multi- be indicated the same way for each of the imported system migration of different teams, with each team software products.

3.3.2. Baseline & Branch Import – Cons VOBs and depots both appear as top-level directories to • In cases where files were renamed or directory users, and both store a set of files. At least one VOB or depot structures reorganized between releases, the historical must exist before any file can be versioned. connection between the files in the old name and A VOB is a container for versioned file contents and the new name are difficult (but possible) to capture. metadata relating to those versioned files. A Perforce depot For example, if a file hello.c in v1.0 of your software contains only the contents of versioned files. All metadata is product was renamed greetings.c in v1.1, the fact that stored in a central database on the Perforce server. greetings.c used to be hello.c requires analysis of your data to detect. Both ClearCase and Perforce provide When mapping VOBs to depots, consider the following: track renames well, but each in their own different way, and that historical linkage of the renaming is • Unlike files in ClearCase VOBs, files can be branched sometimes forgone in BBI migrations. With additional across depots. VOBs in ClearCase are effectively islands to identify refactoring events and layout baselines of code, where depots in Perforce are more transparent in such a way that from/to information is identified, (barring any special access controls). renaming can be captured properly (as opposed to • In Perforce, it is a best practice to manage all digital simply showing a delete of one file and an add of assets, and generally practical to do so because of another, without the connection that the two the particularly efficient handling of binary files are related). in Perforce. This is less common in ClearCase environments due to performance considerations • ClearCase allows versioning of some uncommon, when handling large numbers of binary files. For low-level file types on some platforms, like block example, a software product might consist of source special devices and character special devices that code, software products built from that source code, are not supported in Perforce. Such files will not be and various released configurations of software imported with BBI or any migration strategy. Symbolic products. A separate depot might be assigned fore each, links will be imported, however. e.g. //gizmo, //gizmo-build, and //gizmo-release. 3.3.3. Warnings • Depots can be created in seconds, but can last a • If VCS best practices were not followed, reproducing lifetime. Choose their names wisely! the baselines may be difficult in ClearCase2. For • Depot names should be kept short. // example, if branches were made from /main/LATEST Engineering is OK, //Eng is better. //Eng- rather than from a label on MAIN, getting a config AdvancedTechnologyGroup is a bit long, // spec to represent the baseline from which a branch was Eng-ATG is better. Path names are primary keys in created may involve some guesswork, such as using / many Perforce databases. Shorter pathnames result in main/LATEST with a ‘–time’ clause selecting a best- reduced memory usage, etc. There is no need to go to guess time to represent the point on MAIN at which a extremes, nor are there any painfully short path length branch was created. limits. Limits are platform dependent, and no less than 1024 characters. 4. Terminology and Concepts First, we’ll introduce Perforce equivalents to basic ClearCase 4.2. ClearCase Regions In ClearCase, network registry regions can be employed to concepts, highlighting along the way some things to consider segregate VOBs, such that any given region sees only a subset while planning a migration. of all VOBs in a given ClearCase installation. 4.1. VOBs and Depots A Perforce depot is roughly analogous to a ClearCase VOB 2Unfortunately, this is a common scenario with ClearCase. (Versioned Object Base).

To achieve similar segregation in Perforce, the protections Perforce performs better, and is most scalable, on Linux table is used. Users who were in different regions in platforms running the XFS filesystem. However, Perforce ClearCase would be assigned to different Perforce groups. performs quite adequately on Windows. Access to different Perforce depots would then be managed at the group level. 4.4. Registry and License Servers Perforce does not require license or registry server processes 4.3. VOB Servers vs. “The Server” or hardware to support them. A simple 0.5KB license file In ClearCase environments, there may be multiple VOB on the Perforce server machine drives the Perforce license server processes, possibly distributed among multiple VOB mechanism. For very large environments, where managing server machines. With Perforce, a single Perforce server may individual users can be burdensome as people come and go be adequate for any given installation3. The Perforce server on a daily basis, Perforce can provide alternative licensing process, P4D, runs on a single machine. P4D is frugal with schemes that allow extra licenses for potential growth. system resources, exceedingly so compared to ClearCase. One P4D process can scale to support extremely large 4.5. Release Servers and Installation With ClearCase, it is important to carefully manage server environments (e.g. 10,000+ users) on a single server using and client versions, to ensure users run client software that enterprise-grade server machines. is compatible with the current version of the server. To aid One of the first steps in any migration is to setup Perforce in ensuring consistency, some ClearCase installations deploy hardware in a data center somewhere. See the General a Release Server, a defined network resource from which all Performance Recommendations for information useful in users are expected to download correct versions of client capacity planning for your primary server. software. This is a more scalable alternative than making sure everyone has the installation CD available. It is common to allocate two or three identical server machines to Perforce, to achieve High Availability and With Perforce, all client components (and even the server Disaster Recovery goals. A typical configuration is to have software) install in minutes over the web. More importantly, two servers (a primary and a hot spare) in a primary data Perforce clients and the server have a very loose forward center, and a third server (warm spare) in another data and backward compatible relationship, because of a smart, center located far from the primary data center. version-aware client-server protocol. Users can generally run client versions that are older or newer than the server. Client 4.3.1. Operating System Selection programs simply hide or disable those features that require Just as with ClearCase, the primary factor in selecting an newer versions of the server, and new server versions rarely operating platform for Perforce in most environments is require client upgrades. the platform that local IT is most comfortable supporting. In mixed Windows/*nix environments, Unix platforms are Perforce supports the concept of centrally configured, almost invariably selected for ClearCase, for case sensitivity automated deployment of Perforce for large Windows sites reasons and due to its reliance on effectively mono- (see Automated Deployment of Perforce). Such sites can directional (Unix  Windows) filesystem mounts to make be used to ensure that users download consistent, trusted VOB data accessible to clients on both Unix and Windows. versions of software that are supported by IT and/or Release Engineering staff. However, due to extreme compatibility With Perforce, only TCP connection is needed between clients and servers. Further, the case sensitivity behavior of Perforce server can be configured independently of the 3Deploying multiple Perforce server instances within an platform. Thus, with Perforce, the server can be configured enterprise is possible and common. For purposes of this on Windows or *nix in multi-platform environments. paper we consider only the single-server-per-enterprise approach, as that best suits most ClearCase migration scenarios.

and extreme ease of installation, maintaining such areas is like branch mastership, scheduling batch replication, etc. much less of a priority than in ClearCase environments. Once hardware is available, proxy servers can be setup in minutes and require virtually no maintenance. 4.6. View Servers, Protecting Unversioned and Checked Out Files Second, Perforce replica servers provide read-only access Perforce stores all metadata in databases on the central to all data (file content and metadata). Perforce replicas server, managed by the P4D process, and nowhere else4. are more capable than proxy servers and have a small There is no equivalent of a view server process, and no need administrative footprint. Perforce replicas provide improved for administrators to allocate and configure view server performance for remote teams and automated processes machines. From a user perspective, there is no need to start like continuous integration builds, as all read-only data is or stop View Server processes; no such entities exist. serviced locally. Data consistency is maintained because there is still one canonical representation of important data When dynamic views are used, View Server machines on the central server. contain the contents of checked out and unversioned view private files. Some organizations back up view storage areas Replicated VOB servers generally run on server machines regularly to protect against loss of such files. If protecting equivalent to the primary server, and thus requiring similar- checked out and unversioned files is a priority, you will tiered data centers. Due to the significant investment need to address this when migrating to Perforce. In Perforce, in licenses, hardware, and administrative overhead, unversioned and checked out files are not available to the MultiSite installations are used only in cases where major server, and are not backed up. However, P4Sandbox provides development centers exist, and are of little use in cases a local repository and other features to the end user, and where many small teams are spread out. can be used to version work-in-progress or work that is not intended to be shared. By contrast, Perforce Proxy servers are lightweight programs that can run on desktop-grade hardware, even in enterprise Some organizations devise infrastructure to protect environments. Proxy servers are so lightweight in terms unversioned and checked out workspace files in Perforce, of hardware resource demands that they can be deployed such as requiring that users store workspaces on network anywhere that even a few developers gather. In some cases, drives that are backed up. More often, we simply stress to individual users deploy Perforce Proxy instances in small users during training that such files are no longer backed up, offices without IT support. and encourage them to avoid keeping files checked out for too long, making use of sandbox branches or P4Sandbox Perforce replicas require more powerful hardware than a if needed. proxy server, but have a small administrative footprint and are useful for small or medium sized teams as well as larger 4.7. ClearCase MultiSite vs. Perforce Proxies sites. If your ClearCase environment relies on MultiSite, several Perforce components provide a flexible architecture that There are no additional cost or license issues to deal with delivers similar support for remote development. when deploying a Perforce Proxy or replica server.

First, the Perforce Proxy mechanism is simple and effective. 4.8. Replacing ClearCase Perforce proxies cache the contents of versioned files at Views with Perforce Workspaces workspace remote sites, greatly reducing the dependency on the WAN. The term is familiar to both ClearCase and Proxies do not cache any metadata, thereby ensuring there is Perforce users, and is similar to the extent that it’s what one single source of state information, and eliminating the need for specialized and administration-intensive concepts 4Some GUI programs temporarily cache metadata in running processes, but such information is not persisted.

developers use to manage files under version control on their changelist, even though it affects only a small subset of the local machines. repository, can be used to describe the state of every file in the repository. With ClearCase, it is typical for a developer to maintain several workspaces, or views. Developers working on Branches in Perforce are represented as directories, making multiple branches typically use a different view for each it easy to use a combination of branches and changelist activity, working in one view at a time. For example, a numbers to represent a baseline. Alternately, labels can developer might maintain a joe_user_main_dev view with reference changelist numbers limited to an identified scope a config spec selecting /main/LATEST versions, and a in the server, where the scope is typically the directory separate joe_user_rel_2.3 view selecting representing a particular branch. /main/REL2.3/LATEST5 versions. 4.10. Unified Change Management (UCM) A Perforce client spec, a form controlling the definition of UCM adds a layer of process to base ClearCase. We strongly a workspace, determines the subset of files from the server recommend viewing The Flow of Change, a 56 minute that are visible in the workspace. Branches in Perforce Google Tech Talk in which Laura Wingerd discusses appear to the user as fully populated directory trees. There modeling the flow of change in Perforce. will typically be a directory on the server named MAIN, Perforce streams provide flexible workflow and guidance for and another directory named something like REL2.3. A release management and, when used on conjunction with developer might have a joe_user_dev workspace, which other ALM tools, can largely replace ClearCase UCM. could include both MAIN and REL2.3 directories. Joe could work in both activities at the same time. 4.11. Migration Technical Details not Perforce streams provide some capability to specify Perforce is ClearCase. ClearCase and Perforce “think” which modules are actively in use in a branch and import very differently about the world, and have very different dependencies from other projects. internal representations and modeling of parallel development, branching and merging. The net result to the In Perforce, only user files are stored on the local disk. All user is that both provide good modeling of what you need metadata, including information about the name and to do to achieve parallel development – but one should be contents of a user’s workspace, is maintained on the server. aware of the differences.

4.9. Rethink Label Strategies 4.11.1. Evil Twins Both ClearCase and Perforce provide labels, which can An "Evil Twin" is a scenario where two elements with the be used to identify the versions of files that constitute same name appear in different branches. For example, say a baseline. For many ClearCase users, the use of labels you have a MAIN, DEV_A and DEV_B branches, with each is mandatory. Applying labels is time-consuming, often of the DEV branches parented directly from MAIN. accounting for 30% or more of the time associated with official builds. In DEV_A branch, a developer does a 'ct mkelem' to create a new file element,foo.c. In Perforce, labels are just one way of reproducing baselines. Labels certainly do the job of identify a baseline well Independently in DEV_B branch, a developer does the enough, but other approaches accomplish the same thing same thing -- does a 'ct mkelem' to create a new file element, in ways that are less taxing on the build process, and faster foo.c. and easier to reference than a label. Alternatives to labeling take advantage of Perforce changelists. Each Perforce checkin generates a unique changelist number that reflects the 5This is an oversimplification, since a typical config spec is state of the entire repository at a point in time. Any given several lines or more.

Someone then does a 'ct findmerge' to make files that 4.11.2. Symlinks on Windows originated on DEV_A appear on MAIN. Later, someone Through use of Multi-Version File System (MVFS), does another 'ct findmerge' intending to merge changes ClearCase enables support for symlinks on Windows in from MAIN to DEV_B, including the new foo.c merged to dynamic views. Perforce has no equivalent of a custom MAIN earlier from DEV_A. filesystem, and does not support symlinks on platforms that do not natively support it. Symlinks are supported Which is the real "foo.c" in DEV_B? The one that on Windows Vista, 7, and Server 2008, but not on earlier originated in DEV_A, or the one that originated in DEV_B? versions of Windows. Thus, if there is a reliance on using It's not clear. One is identified as the correct file, and the symlinks on earlier versions of Windows, this must be other is dubbed the evil twin. One might expect them to be accounted for in the migration planning. branch-relations of the same element, but they’re not related in the ClearCase database. As far as ClearCase is concerned, Perforce allows symlinks to be versioned. When a file of they're completely independent elements, referenced in its type ‘symlink’ is brought into a Perforce workspace on a database by different OID (object identifiers). Windows machine without symlink support, it appears as a text file, with the contents being the target path of the The findmerge completes successfully, and you would have symlink. For example, say in a Linux workspace you did ‘ln two foo.cs in the branch, but which ones show in your –s hello.hpp hello.h’. The filehello.h would be a symlink view (the OS will only let one foo.c appear in the directory) pointing to In Perforce, if you sync the is deterministic, but not obvious to most users. ClearCase hellol.hpp. hello.h symlink to a Windows workspace without symlink support, doesn't provide any sort of warning about this. Situations you get a file with the contents being , the path are even worse when there turn out to be "evil twin" “hello.hpp” to the target of the symlink. You do not get the content of directory elements. the pointed-to file, as would occur in a ClearCase snapshot This is one of the more insidious complexities of ClearCase. view. ClearCase admins aware of this potentially confusing scenario sometimes put in "Evil Twin Detection" and "Evil 4.11.3. File Type Mappings and Limitations When migrating from ClearCase to Perforce, the Perforce Twin Prevention" triggers. ‘typemap’, which defines file types based on Perforce From the perspective of migrating data from ClearCase, pathname heuristics, will help ensure that files are added this is murky history — not something to bring forward into with the correct file type mapping. This is especially Perforce, even if you could. Our process for dealing with important for Unicode files. evil twins is to detect instances of them, manually select ClearCase allows versioning of some file special filesystem the “correct” element from the pair, and use ‘ct rmelem’ to objects, such as block special devices, character special eliminate the evil twin. devices and hard links. These have no equivalent in Perforce. In Perforce, it is possible for a similar scenario to occur, If such objects are versioned in ClearCase, you will need to where a file is created independently in two branches. account for that in your migration planning. However, unlike ClearCase, Perforce detects and encourages you to resolve the situation the first time they are merged together. In Perforce, the histories of the two files can be combined and their revision histories united. Instead of having to kill off an evil twin (and lose some history and potentially related defect integration history), you simply have a family reunion and unite the family trees.