Migration design

1. Introduction

This document sets out the high-level requirements for a system to move an organization from use of Perforce jobs, to use of Perforce jobs and defect tracker issues together with the P4DTI. We call this process migration. The document explains the consequences of these requirements for the design of the migration process and tools.

The P4DTI needs to support migration to meet requirement 95. This is Ravenbrook's job000022 and Perforce's job005387.

The intended readership is project developers and management.

This document is not confidential.

2. Requirements

These are the high-level requirements for migration:

1. The migration procedure must not lose knowledge about jobs and fixes (requirement 1).

2. The migration procedure must inspire confidence in its results (requirements 1 and 2).

3. The administrator must be able to carry out the migration (requirements 114 and 115).

4. The migrated system must make the jobs of the developers and managers easier (requirement 2).

5. It must be possible to extend the P4DTI so that it supports migration to new defect trackers (requirement 20).

3. Analysis

This analysis is based in part on [NB 2001-04-19].

3.1. Jobnames

Jobnames are an important part of an organization's knowledge about its product. If an organization has been using Perforce jobs for some time, then these jobnames will appear in plans, code, design, manuals, e-mails, printouts, and people's memories. The migration must not lose this information (migration requirement 1).

It's also important that users of the integrated system be able to tell which job in Perforce corresponds to which defect in the defect tracker. These are conflicting requiurements.

Here are some possible solutions:

1. Use Perforce jobnames for jobs in Perforce, defect tracker names for defects in the defect tracker. Users find the defect corresponding to a job by looking at the P4DTI-issue-id field in the job. Users find the job corresponding to a defect by looking at the "Perforce jobname" field in the defect.

   This solution imposes a burden on the user. (Fails migration requirement 4).

2. Use Perforce jobnames for jobs created in Perforce, but a defect created in the defect tracker gets a job name in Perforce that matches its name in the defect tracker.

   This creates an artificial distinction between issues created in the two systems as well as imposing the burden identified for solution 1. (Fails migration requirement 4).

3. When a job is created in Perforce, give it a name in the defect tracker that is similar or identical to the name of the corresponding job in Perforce. And vice versa for defects created in the defect tracker.

   This creates an artificial distinction between issues created in the two systems. This is not possible in some defect trackers. (Fails migration requirements 4 and 5.)

4. Rename all the Perforce jobs so that their names match the names of the corresponding defects in the defect tracker.

   This loses information. (Fails migration requirement 1).

None of these solutions meets all the requirements. However, the first solution is the best and also the simplest.

Decision 1. In the migrated system, Perforce jobs will have Perforce jobnames and defect tracker issues will have defect tracker names.

3.2. The Perforce jobspec

The P4DTI's default mode of operation is to replace the Perforce jobspec with one of its own choosing. However, it is very likely that the organization has configured their jobspec carefully to match their process, and may have tools that operate on that jobspec. This is certainly true of both Ravenbrook and Perforce.

This means that we can't replace the jobspec without breaking migration requirement 1. The most we can do is to add our own fields to the jobspec.

Decision 2. We will add the P4DTI fields to the jobspec but not otherwise change it.

It follows from decision 2 that we can't use the P4DTI's automatic configuration to work out how the fields in the defect tracker correspond to the fields in Perforce. (The automatic configuration generator constructs a Perforce job field for each defect tracker field that the administrator chooses to replicate.) Each organization must be able to choose how the fields correspond.

Decision 3. Each organization must choose the correspondence between the fields in the defect tracker and the fields in Perforce.

It follows from decision 3 that we're in an "Advanced Configuration" situation [RB 2000-10-16, 8.6]. An organization must construct a field mapping between Perforce and the defect tracker.

3.3. Complications

This section lists situations that complicate the process of configuration and migration.

1. Fields may not be one-to-one between Perforce and the defect tracker.

   Example. You have a single "Description" field (as in the default Perforce jobspec). But TeamTrack requires you to have a "Title" field containing a single line of text, and a "Description" field. In this case, you'd have to come up with some translation scheme: perhaps splitting the Perforce "Description" field into its first line (or paragraph?), forming the TeamTrack "Title", and the remaining lines, forming the TeamTrack "Description" ).

2. Perforce data may not correspond well to defect tracker data.

   Example. You have specified "Priority: high/medium/low" in Perforce, but Bugzilla specifies priorities "P1" to "P5". We're not going to be able to automatically translate these fields: the organization must decide on a translation and implement it.

3. Different concepts in the two systems force you to change some data during migration.

   Example. You have a job "Status" with values "open", "fixed", "ignored", "duplicate", "not_a_bug" and so on. But TeamTrack's workflow support requires you that status be "open" or "closed", with a separate "Resolution" field containing the reason why the issue was closed. So during migration you decide to add a "Resolution" field to Perforce and translate the old "Status" field into a combination of the new "Status" and "Resolution" fields.

4. Not all jobs need to be migrated.

   Many organizations will only want to migrate jobs that are currently open; old jobs should be left alone. But other organizations will want to migrate all jobs so that reports and metrics show the true picture.

5. Defaults need to be provided for defect tracker fields.

   Example. A defect tracker issue generally has more fields than a Perforce job. For example, TeamTrack issues have fields for "Issue Type" (bug, enhancement request, etc.), "Manager", "Tester", "Engineer", "Version", "How Found" and others that are unlikely to be in any organization's jobspec. The organization will need to specify sensible defaults for these fields.

3.4. Usability

Our experience of testing release 0.3.0 (which used advanced configuration) with potential customers was that this kind of configuration was too complicated and error-prone for the average administrator. So any solution requiring "advanced configuration" or something similar will fail migration requirement 3. We believe that many organizations will be unable to use this method to migrate from Perforce to a defect tracker without expert help.

This failing is severe, so we spent some time trying to come up with ways to work round it. However, we couldn't find any way to do this that took account of the complications in section 3.3 and which is affordable.

An approach that might meet all the user requirements would be to have a graphical user interface which presents fields from Perforce and the defect tracker. The administrator will drag the fields around until they match up. Then for each pair of corresponding fields the administrator picks a method for translation; this may also involve pairing up values. Finally, when all is ready, the administrator hits the big "Migrate" button and off it goes. Further widgets would help work around each of the various complications listed in section 3.3.

We estimate that this solution would require at least 12 months of effort for design, implementation and testing (that's around $150,000). We don't believe that this expenditure will be cost-effective.

4. Migration overview

4.1. Migration steps

This is the sequence of steps to migrate from Perforce to the defect tracker.

1. Make a test setup with a test Perforce server containing a copy of your jobs, and a test defect tracker.

2. Develop an advanced configuration [RB 2000-10-16, 8.6].

3. In the advanced configuration, specify both a migration field map and a replication field map. We need two field maps because (1) during migration we need to provide defaults for some defect tracker fields (complication 5) and because data may be being changed during migration (complication 3). Usually the two maps will be similar but subtly different.

   For a defect tracker field which reproduces the contents of multiple Perforce fields, write a single translator which uses the job argument to get at other job fields.

   For a Perforce field which reproduces the contents of multiple defect tracker fields, write multiple translators (i.e. have multiple entries in the field_map list).

4. Specify a migrate_p function to select the jobs to migrate.

5. Test that migration works (it's probably best to start out with a handful of jobs by setting the migrate_p appropriately) then run the consistency checker.

6. When migration works, test that replication works by taking some issues through their life cycles.

7. When everything works satisfactorily, repeat on your real data.

4.2. Robustness

Our experience (based on alpha testing the P4DTI when all configuration was "advanced") is that the steps in section 4.1 will be very hard to follow and possibly beyond the ability of some organizations.

We can make success more likely if we can make the migration robust: in particular, it must be possible to get migration done in one pass, even if there are problems.

This is especially important when an organization has many jobs. TeamTrack can process cases at about 2 per second, so 100,000 jobs may take 54 hours to migrate (each case gets written once and read once). It will not be acceptable to set this going and find out after 53 hours that one of the jobs has a bogus value in it that can't be translated and that the whole thing has to be done again.

Because Perforce isn't very strict about the contents of job fields (and anyway you can override the checking with p4 job -f) we must expect many bogus fields in jobs. These must be translated anyway, with warnings. The administrator can always tidy these up afterwards.

The migration design needs to be idempotent. We should be able to run the migration script several times, each time migrating some more jobs.

4.3. What if an organization can't use this process?

These are the possibilities:

1. Advise the organization not to migrate, but to continue using Perforce jobs.

   This isn't an acceptable solution. Organizations get substantial benefits from a defect tracker, including workflow enforcement and reporting.

2. Leave people to cope with the difficulties of advanced configuration.

   We don't like this. It reflects badly on the P4DTI. It fails requirement 75.

3. Improve the migration process so that it is easy enough.

   This is unacceptably expensive; see section 3.4.

4. Provide consultancy for each organization.

   This suggests a number of questions:

   1. Would Perforce be happy about this?

   2. Who's going to pay for the work?

      I think the end user is going to have to pay in each case.

   3. Who's going to do the work?

      Ravenbrook would be willing to do it for at least the first year. It should be possible to train Perforce consulting partners and TeamShare PSG to do this.

4.4. Miscellaneous requirements

1. Migration should be idempotent. You should be able to run the migration script many times over the same set of jobs and it should do no harm.

   This should not create huge slews of new issues (multiple copies of the same issue). One way to do this would be to check to see if there's already an issue which replicates to a given job.

2. We should be able to use the migration design to allow people to create new jobs in Perforce and have them replicated.

5. Migration design

This design is based on [NB 2001-05-10a] and [NB 2001-05-10b].

Things you need advanced config to do include:

1. Keeping your old jobspec.
2. Keeping your old workflow when using Bugzilla.

The user steps to migration are as follows:

1. Think about requirements and make design decisions. If you have only a handful of jobs (say 20 or less) then it's probably better to migrate "by hand". If you've been through some process where you changed jobspecs in the past you have to worry about how they'll all be translated. Usually fields have been added, items might be deleted from selects. You have to make sure that p4 -G jobs will work and fix up any jobs that don't work. If you have jobs that don't fit your current jobspec, then you're probably going to have write pre_migrate_issue and migrate_issue to handle all instances. Think about: How do I want these to appear as issues? In TeamTrack: Description -> Title + Description In Bugzilla: Description -> Summary + LongDesc In Bugzilla: Status -> Status + Resolution Think about: Are you going to keep your old jobspec or use a new jobspec? What about special fields that don't map well into the defect tracker?
2. Set up test servers to try out migration. You're not going to get everything right the first time. (Need instructions.)
3. Make a new configuration module (configure_xyz.py) whose template is ...
4. Call the old config module to do most of the work?
5. Write pre_migrate_issue, migrate_issue.
6. Design your ordinary configuration so that it generates the correct jobspec.
7. In TeamTrack, migrate the users by hand.
8. migrate.py; check.py; user testing; if not happy, repeat.
9. do this on your production server?

The new command-line script migrate.py just creates a replicator instance and calls its migrate() method.

These configuration items are needed to support replication (eventually these descriptions will be replaced with links to the Integrator's Guide):

1. use_perforce_jobnames: when this is true, the replicator uses ordinary Perforce jobnames for replicated issues.

2. migrate_p: this function is called for each job during migration; iff it returns true, then job is migrated.

3. migration_field_map: this is the field map that is used during migration. It has the same specification as the field_map configuration parameter.

4. migrated_jobspec_description: this is the new Perforce jobspec. After copying the jobs to the defect tracker, the Perforce jobspec is changed to this (if supplied) and issues are replicated back to Perforce.

These methods are added or changed in the replicator class:

1. __init__(): makes a client for the replicator to use when issuing p4 change -o commands. Calls dt.init().

2. check_jobspec(): checks that the Perforce jobspec has the P4DTI fields.

3. create_issue(): applies the migration field map and creates a new issue in the defect tracker.

4. init(): removed. Initializtion has been moved to appropriate places so that the migrate script can run without the replicator checking that it has the right jobspec. Creation of client and calling defect_tracker.init moved to __init__() method. Checking of jobspec moved to new method check_jobspec() and called from the check(), refresh() and run() methods.

5. migrate(): carries out migration.

6. replicate_many(): implements the use_perforce_jobnames feature.

7. update_job(): supports the use_perforce_jobnames feature by recording the jobname of a newly created Perforce job so that it can be passed to setup_for_replication() and thus recorded in the defect tracker.

8. migrate_users(): copies users from Perforce to the defect tracker.

These methods has been added to the defect tracker class (eventually these descriptions will be replaced with links to the Integrator's Guide):

1. add_user(): adds a user to the defect tracker if not already present, and if this is possible given the constraints of the defect tracker (licences etc.).

2. new_issue(): creates a new issue in the defect tracker.

A. References

B. Document History

Copyright © 2001 Ravenbrook Limited. This document is provided "as is", without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this document. You may make and distribute verbatim copies of this document provided that you do not charge a fee for this document or for its distribution.