Perforce Defect Tracking Integration Project
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]The P4DTI documentation set consists of the following manuals:
[Section not written yet. LMB 2000-10-15]
[Section not written yet. LMB 2000-10-15]
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]
This section explains what you will need to install the integration in your organization.
You will need:
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>.
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:
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>.
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]
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.
You must also create a user called "P4DTI-case" in TeamTrack to represent the replicator. (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]) The replicator user must have standard access, and must be a member of the group "Administrators". [This is true in the default database. GDR 2000-10-16]
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
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".
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".
The decisions needed are:
[Section not written yet. RB 2000-09-20]
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]
[There should follow sections on how to implement each of the configuration decisions. RB 2000-09-21]
[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]
[This topic will probably deserve special treatment, but if not, delete this section. RB 2000-09-21]
This section explains how to migrate your defect tracking data to the integrated system.
[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]
[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]
[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]
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]
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.
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:
[Section not written yet. RB 2000-09-20]
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]
[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]
[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]
[Section not written yet. RB 2000-09-20]
[Section not written yet. RB 2000-09-20]
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]
[Section not written yet. RB 2000-09-20]
[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>. |
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. |
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].
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 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/0.3/manual/sag/index.html#1 $