Perforce Defect Tracking Integration Administrator's Guide

For the Perforce/TeamTrack integration you will also need:

1. Perforce licenses for every TeamTrack user who's going to work in Perforce [this will need specifying more precisely];
2. TeamTrack licenses for every Perforce user who's going to work in TeamTrack [this may need specifying more precisely];
3. an installation of TeamTrack (tTrack and/or tSupport) version 4.0.4 or later (but, see below);
4. administrator level access to the TeamTrack server machine;
5. a certain amount of disk space on the TeamTrack server machine [how much?].

As of 2000-10-15, TeamTrack 4.0.4 is not available, so a special pre-release build of TeamTrack, build 4402, must be used. An installer can be downloaded from <http://www.ravenbrook.com/project/p4dti/import/2000-10-13/teamtrack-4402/ttrk4402.exe>.

4. Installing the software

Make sure you have already installed all the prerequisite software (see section 3).

You may want to configure the integration to start automatically when the machine boots. This is covered in "Going Live" (section 9) after configuration and testing.

5. Configuring the software

This section describes the configuration decisions that each organization has to make, and how to configure the integration to implement those decisions. It also has example configurations, and describes common pitfalls.

Configuration is not a simple task. Each organization must make its own configuration decisions based on its process and workflow. Therefore you should read all of "Configuration Decisions" [5.1] before you start to configure the software.

The integration's configuration will also need to be updated when the organization changes in various ways. See "Maintaining the Configuration" [no section yet] for details.

The integration is by default configured to work with the defect tracker's default database. In the case of TeamTrack, the integration is configured for the sample database, installed by default in "C:\Program Files\TeamShare\TeamTrack\database\tTrackSample.mdb".

5.1. Configuration decisions

The decisions needed are:

1. which TeamTrack cases will be replicated into Perforce, and in the case of multiple Perforce servers, into which server;
2. which TeamTrack case fields will be replicated in Perforce;
3. how TeamTrack case states will correspond with Perforce job status keywords;
4. which users will be driving TeamTrack from Perforce, and how their TeamTrack user names correspond to their Perforce user names;
5. who will handle conflicts between TeamTrack and Perforce;
6. who will handle day-to-day maintenance of the integration;
7. and lots more.

[Section not written yet. RB 2000-09-20]

5.2. How the integration is configured

This section describes how the integration is configured. [For example, is it done by setting registry keys, or by editing Python variable definitions and functions, or what? What does the administrator have to do to configure the system? How does the administrator check the configuration? RB 2000-09-21]

5.3. Implementing your configuration decisions

[There should follow sections on how to implement each of the configuration decisions. RB 2000-09-21]

5.4. Example configurations

[We should include a simple example which would suit organization new to defect tracking, or who have just migrated from Perforce jobs, and a more complex example, more suitable for TeamTrack users with non-trivial workflows. RB 2000-09-21]

5.5. Multiple Perforce servers

[This topic will probably deserve special treatment, but if not, delete this section. RB 2000-09-21]

6. Migrating your defect tracking data to the integrated system

This section explains how to migrate your defect tracking data to the integrated system.

6.1. Migrating from Perforce jobs

[Section not written yet. This will probably involve added P4DTI fields to the set of jobs that the organization wants migrated. We should explain how to do that. RB 2000-09-21]

6.2. Migrating from TeamTrack

[Section not written yet. This might be trivial, but it might involve adding P4DTI fields to the set of TeamTrack cases that the organization wants migrated. We should explain how to do that. RB 2000-09-21]

6.3. Migrating from Bugzilla

[Section not written yet. This might be trivial, but it might involve adding P4DTI fields to the set of Bugzilla bugs that the organization wants migrated. We should explain how to do that. RB 2000-09-21]

7. Testing

This section describes how you can test the integration that you've set up to make sure it's working properly.

[A good approach to take in this section would be to create a test issue and take it through a complete life-cycle (i.e. through the workflow). We can't know what the workflow will be at the organization, but we can use an example. RB 2000-10-07]

7.1. Testing data replication

Run consistency checking scripts, that will be part of the P4DTI product. [Derived from GDR's "check_consistency" method in "//info.ravenbrook.com/project/p4dti/master/code/replicator/replicator.py#26".]

Examine the database by hand using, e.g., Microsoft Access, to make sure it looks like the Perforce data is there.

7.2. Testing the Perforce interface

This is testing the integration as if you were a user of Perforce. You should go through a typical sequence of actions that you expect your developers to go through. A "dry run".

[It's probably not necessary to test the integration from every Perforce interface, but we should describe how to do it for each of them in the manual. Advise the administrator to use whichever their developers are most likely to use.]

The three main interfaces are:

1. Command line
2. GUI
3. Development environment integrations

[Section not written yet. RB 2000-09-20]

7.3. Testing the defect tracker interface

This is testing the integration as if you were a user of the DT.

[Probably need sub-sections for each DT.]

[Section not written yet. RB 2000-09-20]

8. Training and documentation

[We're going to provide the UG which will be "how to" documentation for the use cases and requirements. But this section will recommend getting the users together and telling them about the integration and how to use it, in overview. LMB suggests we provide a presentation outline. GDR suggests that we cover some key stuff that users should or shouldn't do (e.g. "don't edit the P4DTI-*" fields in jobs"). RB will write this presentation, as it's needed for the alpha programme anyway. We need to cover how to use it, and what to do when it goes wrong, for example, when a conflict happens, or when they come across a conflicting issue. This presentation material will also be useful for the user guide. RB 2000-10-07]

[Section not written yet. RB 2000-09-20]

9. Going live

[When the admin is configuring and testing, he doesn't want to use the real database. We should explain this earlier on. And we'll need to explain how to make the integration work on the real data smoothly. We can provide a plan, and contingency plans for if things go wrong. For example, recommend coming in early in the morning or over a weekend. We can estimate how long it will take.

[Configuration should've taken place on a duplicate of their real data. This might not be feasible if the real data is a 10Gb Perforce repository and a 100Gb corporate Oracle database. We'll need to think about that one.

[They'll need to re-run the testing on the live system as well. (The earlier testing was to make sure the configuration worked, this is to make sure the live system is working.)

[They should configure the replicator to start automatically when the system comes up, and check that it does.

[They should then watch the system working for a while. We should list things to look out for. RB 2000-10-07]

10. Maintaining the integration

[Section not written yet. RB 2000-09-20]

11. Administering the integration

[Section not written yet. RB 2000-09-20]

12. Uninstalling the integration

First tell your staff that you're uninstalling the integration. Ask them to stop using either Perforce jobs or the defect tracking, whichever you're not planning to use in future. Then simply stop the replicator process. Remove any hooks that start it again, such as Windows services, entries in "/etc/rc.d", and so on.

That's all you need to do. The rest of this section deals with ways to remove data created by the integration, if you want to do that. We don't recommend it. We recommend you keep all your records.

If you intend to use Perforce jobs in future, you might consider removing the P4DTI fields from the Perforce jobspec, so that they don't clutter up future jobs or confuse users. We suggest you don't re-use the field numbers, though, so that you can easily re-install the integration later.

[We should talk about how to delete the replicator installation itself, most likely by removing the contents of a directory. We should talk about removing just one replicator when there are several running. RB 2000-10-15]

13. Troubleshooting

[Section not written yet. RB 2000-09-20]

14. Glossary

A. References

[RB 2000-09-07]	"Sketchy documentation outlines" (e-mail message); Richard Brooksby; Ravenbrook Limited; 2000-09-07.
[LMB 2000-09-14]	"first cut at a documentation plan" (e-mail message); Leah Bateman; Ravenbrook Limited; 2000-09-13.
[RB 2000-10-07]	"Notes from documentation meeting, 2000-10-07" (e-mail message); Richard Brooksby; Ravenbrook Limited; 2000-10-07.
[GDR 2000-09-04]	"TeamTrack database schema extensions for integration with Perforce (version 0.3)"; Gareth Rees; Ravenbrook Limited; 2000-09-04; <http://www.ravenbrook.com/ project/p4dti/ version/0.3/ design/teamtrack-p4dti-schema/>.

B. Document History

2000-08-10	RB	Created placeholder.
2000-09-11	GDR	Added instructions for demonstrating the integration and notes on version 0.2.
2000-09-20	RB	Replaced demo instructions with full documentation outline from documentation plan.
2000-10-15	RB	Added installation and uninstallation sections, and other sections discussed in [RB 2000-10-07]. Removed parts specific to Ravenbrook Information System.

C. Data Representation

This section describes the way in which the integration represents the Perforce data in the defect tracking system's database (DTDB), so that organizations can write queries on the combined Perforce and defect tracking data [requirement 68].