Ravenbrook / Projects / Perforce Defect Tracking Integration / Version 1.5 Product Sources / Design
Perforce Defect Tracking Integration Project
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.
Migration requires the following user steps:
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.
Edit Perforce jobs so they match the jobspec [GDR 2001-11-14, 4.4].
The script check_jobs.py
assists with this
step.
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:
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.
Apply the field map.
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.
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.
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.
You need to delve into the Integrator's Guide and write advanced configurations if you want to:
These are the possibilities:
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.
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.
Improve the migration process so that it is easy enough.
This is likely to be unacceptably expensive; see [GDR 2001-12-02, 5.4].
Provide consultancy for each organization.
This suggests a number of questions:
Would Perforce be happy about this?
Who's going to pay for the work?
I think the end user is going to have to pay in each case.
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.
[GDR 2000-10-16] | "Perforce Defect Tracking Integration Integrator's Guide"; Gareth Rees; Ravenbrook Limited; 2000-10-16. |
[GDR 2001-11-14] | "Perforce Defect Tracking Integration Advanced Administrator's Guide"; Gareth Rees; Ravenbrook Limited; 2001-11-14. |
[GDR 2001-12-02] | "Requirements, solutions and analysis for migration"; Gareth Rees; Ravenbrook Limited; 2001-12-02. |
2001-06-01 | GDR | Created. Added requirements. |
2001-06-25 | GDR | Added analysis and design. |
2001-12-02 | GDR | Moved analysis to separate document [GDR 2001-12-02]. Brought up to date with release 1.3.2. |
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.
$Id: //info.ravenbrook.com/project/p4dti/version/1.5/design/migration/index.html#3 $
Ravenbrook / Projects / Perforce Defect Tracking Integration / Version 1.5 Product Sources / Design