Perforce Defect Tracking Integration Project


Perforce Defect Tracking Integration Administrator's Guide

Richard Brooksby, Ravenbrook Limited, 2000-08-10

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 release, 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.

[What does this document tell you? Who should be reading it? Reqs 1-5. LMB, 2000-10-16]

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]

3. Prerequisites for installing the software

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

You will need:

  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 Perforce version 2000.2 or later (but, see below);

As of 2000-10-15, Perforce 2000.2 is not available, so a special pre-release Perforce client, Rev. 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>.

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:\p4test
p4d -p 0.0.0.0:1667 -r C:\p4test

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 the P4DTI replicator to create a user of its own (it will be called "P4DTI-case" by default. This can be changed in the replicator configuration. See section 5. [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".

For the Perforce/TeamTrack integration you will also need:

  1. an installation of TeamTrack (tTrack and/or tSupport) version 4.0.4 or later (but, see below);
  2. Perforce licenses for every TeamTrack user who's going to work in Perforce [this will need specifying more precisely];
  3. TeamTrack licenses for every Perforce user who's going to work in TeamTrack [this may need specifying more precisely];
  4. administrator level access to the TeamTrack server machine;
  5. a certain amount of disk space on the TeamTrack server machine [How much? Probably a few hundred K for the integration, plus space for logs. RB 2000-10-16].
  6. Install Python 1.5.2 for Windows, and the Windows extensions. These are available from <http://www.ravenbrook.com/project/p4dti/import/1999-04-13/python-1.5.2/py152.exe> and <http://www.ravenbrook.com/project/p4dti/import/2000-05-06/python-win32all-132/win32all-132.exe> respectively.

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

We recommend stopping the TeamTrack Broker Service while installing build 4402, as a precaution. We also recommend installing it in a separate directory from your usual TeamTrack installation (e.g., in "C:\Program Files\TeamShare\TeamTrack-4402"). Use the "re-install" option rather than the "upgrade" option when the installer gives you this choice. See figure 1.

Figure 1. TeamTrack install options
Screen
shot of TeamTrack install options

Make sure that TeamTrack has enough licences for the P4DTI replicator to have a user of its own. [We should tell them what to do if it doesn't. They probably need to go back to TeamShare and ask for a special extra licence. TeamShare need to make arrangements to cope with this. RB 2000-10-16]

4. Installing the software

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

On the TeamTrack server machine, run the "p4dti-teamtrack-release.exe" installer program (where release is the release number, such as 0.3.1). This will unpack the integration. We recommend installing the integration in "C:\Program Files\P4DTI\" but you can ask the installer to put it somewhere else.

Use the registry editor ("regedt32") to set two registry settings. Select the key "HKEY_LOCAL_MACHINE\Software\TeamShare\TeamTrack", and create the values "VC Integration" with string contents "perforce" and the value "VC Update Group" with string contents "Everyone". See figure 2.

Figure 2. TeamTrack registry keys
Screen shot of
TeamTrack registry keys in the Windows Registry Editor

Make sure that TeamTrack is using a sample database, and not any live database. Don't use the sample database distributed with the TeamTrack build 4402, but instead use the TeamTrack 4.0.3 database (distributed with the integration). To choose this database, run the TeamTrack administrator. Select "Connect" from the "File" menu. Select "ODBC..."; select the "System DSN" tab; select "Add..." to add the data source; select "Microsoft Access Driver (*.mdb)"; select "Finish"; give the data source a name and description; select "Select..."; select the path "C:\Program Files\P4DTI\tTrackSample.mdb".

Next, create a user called in TeamTrack to represent the replicator. The replicator expects this user to have the user name "P4DTI-" plus the replicator identifier; for example, "P4DTI-case" if the replicator identifier is "case". You can choose any other user name you like for the replicator, but you must then configure the replicator to use the name you have chosen. See section 5.

In the TeamTrack Administrator, select the "Users" tab, then select "Add...". In the "General" tab, enter the user name you decided on and give the user "Standard" access. See figure 5. You can give the replicator user a password, but if you do you'll have to configure the replicator to use it (see section 5).

Figure 5. New user: general tab
Screen shot
showing the general tab for creating a new user in TeamTrack
Administrator

The replicator user must have all access privileges. In the sample database, you can achieve this quickly by making the user a member of the group "Administrators". See figure 6.

Figure 6. New user: membership tab
Screen shot showing the membership tab for creating a new user in
TeamTrack Administrator

Add these fields to the "Fields" section of the Perforce jobspec [Perforce 2000-10-11, chapter 5]. 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

You must also 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: replicate/wait/keep/discard
  Preset-P4DTI-action: replicate

If you are using the TeamTrack sample datavase then you'll need to change the "Values-Status" field in the Perforce jobspec so that the replicated status values from the sample workflows are legal in Perforce. The "Values-Status" field should at least include the values "assigned/closed/deferred/new/resolved". For a real installation, you'll need to decide how states in TeamTrack map to and from statuses in Perforce, and configure the replicator accordingly. This is described in detail in section 5.

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

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

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/>.
[Perforce 2000-10-11] "Perforce 2000.1 System Administrator's Guide"; Perforce Software; 2000-10-11; <ftftp://ftp.perforce.com/ /pub/perforce/r00.1/ doc/manuals/p4sag/p4sag.pdf>.

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.
2000-10-16 RB Merged with master sources and GDR's demonstration instructions for version 0.2. More edits required to make this consistent with the master sources.

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

C.1. TeamTrack Schema Extensions

Details of the schema extensions for TeamTrack aren't yet in the manual. Full documentation is available in the design document "TeamTrack database schema extensions for integration with Perforce (version 0.3)" [GDR 2000-09-04].


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.

$Id: //info.ravenbrook.com/project/p4dti/version/0.3/manual/sag/index.html#8 $