Requirements, solutions and analysis for migration

1. Introduction

This document sets out the requirements for migration from Perforce jobs to a defect tracker. It analyzes possible solutions and sets out recommendations for the design.

This document is based on the original migration design [GDR 2001-06-01] and on [NB 2001-04-19]; the material was moved here because it's not design but analysis.

The intended readership is project developers and management.

This document is not confidential.

2. Requirements

These are the high-level requirements for migration:

1. Customers are able to migrate from using Perforce jobs to a Perforce integrated defect tracker (requirement 120).

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

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

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

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

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

7. The migration implementation must be affordable (requirement 79).

3. Complications

This section lists situations that complicate the process of configuration and migration, and which need to be taken into account when designing a solution.

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 only want to migrate jobs that are currently open; old jobs should be left alone. But other organizations 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 needs to specify sensible defaults for these fields.

4. Jobnames

How should the Perforce jobs be named in the migrated system? This is a problem that's common to all migration solutions, so we consider it separately in this section.

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 appear in plans, code, design, manuals, e-mails, printouts, and people's memories. The migration must not lose this information (migration requirement 2).

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

Here are the 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 5).

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 5).

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 2).

Note that none of these solutions meets all the requirements.

Decision. Jobs originally created in Perforce retain their names. Jobs originally created in the defect tracker either get names in Perforce matching their names in the defect tracker; or else get Perforce-style names that don't match. This is the choice of the P4DTI administrator.

5. Migration solutions and analysis

This section describes some migration solutions and analyses them in terms of the migration requirements (section 2).

5.1. Migration using advanced configuration

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

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 [GDR 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 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 are 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.

5.2. Analysis

Advantage: allows the organization to keep its old jobspec. Simple and cheap to implement.

Disadvantages: our experience (based on alpha testing the P4DTI when all configuration was "advanced") is that the steps in section 5.1 are very hard to follow and possibly beyond the ability of some organizations. So this solution will fail migration requirement 4.

It is likely to take several attempts to specify the replication field map in a robust way. This is especially frustrating 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 is not 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. This fails migration requirements 3 and 4.

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.

5.3. Migrating using a GUI

Make a graphical user interface which presents fields from Perforce and the defect tracker. The administrator drags 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.

5.4. Analysis

Advantage: this is the only design we can think of that might meet migration requirement 4.

Disadvantages: it's not as simple as the paragraph suggests. Further widgets would be needed to work around each of the various complications listed in section 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 is cost-effective.

5.5. Migrating without advanced configuration

This is similar to the procedure outlined in section 5.1, but it doesn't use advanced configuration.

1. Make a test Perforce server and defect tracker server. Work out the new workflow and thus the new Perforce jobspec.

2. Write

3. Write a migrate_p function to select the jobs to migrate.

4. Write a translate_jobspec function to translate jobs from the old jobspec to the new jobspec.

5. Write a prepare_issue function to provide default values and satisfy other defect tracker constraints.

6. Migrate jobs, refresh Perforce (this updates the jobspec), then run the consistency checker.

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

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

5.6. Analysis

Advantages: This is straightforward to implement. It is simple enough that it might meet migration requirement 4. The later steps of issue translation can be re-used to replicate jobs created in Perforce.

Disadvantages: Replaces the Perforce jobspec, so the organization has to revise its process and any tools that operate on that jobspec. So this fails migration requirement 2.

However, an organization still has the option of using advanced configuration and preserving their jobspec.

6. Conclusion

No solution meets all the requirements. However, the solution in section 5.5 comes closest. It fails migration requirement 2, but we believe it meets the requirements of the majority of organizations cheaply. Advanced configuration is available for organizations that need it, although at the expense of migration requirement 4.

The solution in section 5.3 can be considered when resources permit.

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.