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 requirements 120 and 121. (The failure to meet these requirements is recorded as job000022 and job000249 respectively). See [GDR 2001-12-02] for requirements analysis, proposed solutions, and detailed analysis.

The intended readership is project developers and management.

This document is not confidential.

2. Migration procedure

2.1. Migration

Migration requires the following user steps:

1. Migrate users from Perforce to the defect tracker [GDR 2001-11-14, 4.3].

   The script migrate_users.py automates this step.

   The defect tracker method add_user actually adds the user.

   TeamTrack has no programmatic approach to adding users. We handle this by not implementing add_user for TeamTrack. The migrate_users.py script refuses to run if this method is not available.

2. Edit Perforce jobs so they match the jobspec [GDR 2001-11-14, 4.4].

   The script check_jobs.py assists with this step.

3. Migrate jobs to the defect tracker [GDR 2001-11-14, 4.10].

   The script migrate.py automates this step.

   The defect tracker method new_issue creates a new issue. A period of creating new issues is bracketed by calls to the defect tracker methods new_issues_start and new_issues_end. In the Bugzilla integration, these are used to acquire and release locks, and to send e-mail notifications in a batch.

   We don't want to force people writing new integrations to support migration. So the migrate.py script refuses to run if the three defect trackers methods are not available.

   The configuration parameter migrate_p controls which issues are migrated.

   Translation of a job to an issue goes through three steps:

   1. Translate the job from the old jobspec to the new jobspec [GDR 2001-11-14, 4.7].

      The replicator calls the translate_jobspec_advanced configuration parameter to do this. By default, this just calls the translate_jobspec configuration parameter (which has a simpler interface). But it's available for people writing advanced configurations.

   2. Apply the field map.

   3. Finish preparing the issue by satisying defect tracker constraints [GDR 2001-11-14, 4.8].

      The replicator calls the prepare_issue_advanced configuration parameter to do this. By default, this sets up some defaults, then calls the prepare_issue configuration parameter (which has a simpler interface). But it's available for people writing advanced configurations.

4. Refresh Perforce jobs [GDR 2001-11-14, 4.10].

   It's important that refreshing not delete jobs, because that deletes fixes, and then we might be unable to restore fixes from the defect tracker because of workflow changes. So refreshing doesn't delete jobs, it just updates them.

2.2. Replication of new issues

Replication of new issues from Perforce shares implementation and configuration with migration. As with migration, you can't replicate new issues from Perforce usless your defect tracker implements the necessary methods.

The P4DTI administrator must write a replicate_job_p function to select the jobs that get replicated, and a prepare_issue function to prepare them for the defect tracker.

2.3. Advanced config

You need to delve into the Integrator's Guide and write advanced configurations if you want to:

• Keep your old jobspec.
• Keep your old workflow when using Bugzilla.

2.4. 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 likely to be unacceptably expensive; see [GDR 2001-12-02, 5.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.

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.