Perforce Defect Tracking Integration Administrator's Guide

1. Introduction

This is the Perforce Defect Tracking Integration 0.3 System Administrator's Guide.

You should not be administrating the Perforce Defect Tracking Integration 0.3. It is an alpha version, only intended for use during alpha testing with P4DTI project staff on site. We recommend that you do not use the integration with live TeamTrack or Perforce servers. The integration may destroy your data. See the project overview for information about planned releases.

This is outline documentation, still in development.

1.1. The P4DTI documentation set

The P4DTI documentation set consists of the following manuals:

[Section not written yet. LMB 2000-10-15]

1.2. Where to turn for more help

[Section not written yet. LMB 2000-10-15]

2. Overview of the software

This section describes what the integration does and how it does it, and provides a summary of the process of installing the integration in your organization.

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

[It needs to say something about the organization of the integration in terms of machines. There are several components, which can run on different machines. Explain configuration decisions. GDR 2000-10-19]

3. Prerequisites for installing the software

This section explains what you will need to install the integration in your organization.

You will need the following:

1. The right experience and skills [derive from requirements].
2. A copy of a P4DTI product release [insert range to which this manual applies].
3. An installation of a Perforce server of version 2000.1 or later and a Perforce client of version 2000.2 or later (but, see below).
4. Perforce licenses for every defect tracking user who's going to work in Perforce, plus one for the replicator [this will need specifying more precisely].
5. A backup of your Perforce repository, to make sure you don't lose any data. See [Perforce 2000-10-11, chapter 2].

As of 2000-10-19, Perforce 2000.2 is not available, so a special pre-release Perforce client, P4/NTX86/2000.1/17595 (2000/09/28), must be used by the replicator. This client can be downloaded from <http://www.ravenbrook.com/project/p4dti/import/2000-09-28/p4-client-ntx86/p4gdr.exe>. You'll need to specify the location of this client executable when you configure the replicator (see section 5).

We recommend that you create a new Perforce repository when testing the integration. Create a directory for the repository, then launch a new Perforce server. For example:

mkdir C:\Program Files\P4DTI\test-repository
p4d -p 0.0.0.0:1667 -r "C:\Program Files\P4DTI\test-repository"

The address and port number you choose for the new Perforce respository will need to be entered into the replicator configuration. See section 5.

Make sure that Perforce has enough licences for every user of the integration (that is, all the Perforce users and all the defect tracking users), plus one for the P4DTI replicator to create a user of its own. [This should be more specific when we have specific instructions. RB 2000-10-16] If you don't have enough licences you can contact Perforce Software for a free "daemon licence".

4. Installing the software

[This section and the next need a lot of organizing. Much of what's in this section at the moment is really configuration, or else depends on configuration decisions. GDR 2000-10-19]

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

You need to make the following configuration decisions now.

1. The directory to install the integration in. We recommend "C:\Program Files\P4DTI\".
2. The replicator identfier. We write "RID" to refer to the replicator identifier. [Need to explain what this identifier is, what the consequences of this decision are. Do we have a recommendation? GDR 2000-10-19]

Update the Perforce jobspec to add the fields required by the integration, as described below. See [Perforce 2000-10-11, chapter 5].

1. Run the command "p4 -p 127.0.0.1:1667 jobspec" (use the address and port for the Perforce server you're using for the integration).

2. Add the following fields to the "Fields" section of the Perforce jobspec. It's not essential that the field numbers be as shown, but we recommend you keep them the same if possible.

   	110 P4DTI-filespecs text 0 default
   	111 P4DTI-rid word 32 required
   	112 P4DTI-issue-id word 0 required
   	113 P4DTI-user word 32 always
   	114 P4DTI-action select 32 required
   

3. Add these other entries at the bottom of the Perforce jobspec:

   Preset-P4DTI-rid: None
   Preset-P4DTI-issue-id: None
   Preset-P4DTI-user: $user
   Values-P4DTI-action: wait/keep/discard/replicate
   Preset-P4DTI-action: replicate
   

4. Change the "Values-Status" entry so that states can be replicated from the defect tracker.

   If you are using the TeamTrack sample database and a new Perforce repository, it should look like this:

   Values-Status: open/suspended/closed/assigned/deferred/new/resolved
   

   For a real installation, you'll need to decide how states in the defect tracker map to and from statuses in Perforce, and configure the replicator accordingly. This is described in detail in section 5.

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.

The integration is configured by editing definitions in Python. The configuration for a release is defined in the file "config_DEFECT_TRACKER.py" in the installation directory, "C:\Program Files\P4DTI" by default. (For example, The configuration for the TeamTrack release is in the file "config_teamtrack.py".) This file builds two objects which are then used by the Python programs that run the replicator and check the consistency of the database. The "dt" object represents the interface to the defect tracker, the "r" object represents the replicator itself. Here's an example:

dt = dt_teamtrack.dt_teamtrack(rid, sid, teamtrack_config)
r = replicator.replicator(rid, dt, replicator_config)

"rid" is the replicator identifier, "sid" is the Perforce server identifier, "teamtrack_config" and "replicator_config" are Python dictionaries mapping name to value for each configuration parameter. The next section lists the configuration parameters.

[Perhaps there should be a "quick start" section here telling you the minimum you need to do to get going. This would say something like, "go into config_teamtrack.py and provide values wherever it says ????". GDR 2000-10-19]

[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]

Replicator configuration parameters:

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.

Important note: The replicator does not currently start automatically. You must start it yourself. To do this, start a command window, go to the P4DTI installation directory ("C:\Program Files\P4DTI\" by default, see above). Run the command "python run_teamtrack.py".

[What should you expect to happen? GDR 2000-10-19]

To stop the replicator, hit Control-C and wait for the replicator to next poll (10 seconds by default).

[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 the consistency checker. To do this, start a command window, go to the P4DTI installation directory ("C:\Program Files\P4DTI\" by default, see above). Run the command "python check_teamtrack.py".

[What should you expect to happen? GDR 2000-10-19]

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

[What's a good way to format this section? GDR 2000-10-19]

Problem. A replication failed and a conflict was reported. I went info Perforce and set the action to "keep". But the same conflict happened again.

Analysis. When you set the action to "keep", the replicator tries to replicate again. If it failed before because the data does not pass the consistency checks, it will most probably fail again now for the same reason.

Solution. Figure out what went wrong, fix the problem in the defect tracker or in Perforce, and only then set the action to "keep" or "discard".

[No doubt many more to add here. When we have message ids we can have an index of troubleshooting advice by message id? GDR 2000-10-19]

14. Glossary

A. References

B. Document History

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

Copyright © 2000 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 copies and derivative works of this document provided that (1) you do not charge a fee for this document or for its distribution, and (2) you retain as they appear all copyright and licence notices and document history entries, and (3) you append descriptions of your modifications to the document history.