PERFORCE DEFECT TRACKING INTEGRATION KIT README
Richard Brooksby, Ravenbrook Limited, 2001-03-27
CONTENTS
1. Introduction
2. Getting started
3. The structure of the kit
4. Developing using the kit
5. Testing
6. Building and testing a release
7. Contributing your work
8. Getting help
1. INTRODUCTION
This is the Perforce Defect Tracking Integration Kit -- a complete set
of sources for modifying or adapting the P4DTI, or for extending it to
work with other defect tracking systems.
This document is a brief introduction to the kit. For detailed
instructions on integrating Perforce with defect trackers, see the P4DTI
Integrator's Guide [GDR 2000-10-16].
The readership of this document is anyone who wants to modify, adapt, or
extend the P4DTI.
This document is not confidential.
2. GETTING STARTED
The P4DTI Integrator's Guide [GDR 2000-10-16] will tell you most of what
you need to know about extending the system. You'll find it in
"manual/ig/". The design documents ("design/") will tell you a great
deal more. Try not to dive right in there and start coding. The P4DTI
is more complicated than it might at first appear, because it tries to
do the right thing in a large number of different circumstances.
3. THE STRUCTURE OF THE KIT
The Integration Kit is just a copy of the sources used to develop and
maintain the P4DTI at Ravenbrook Limited .
The "sources" are all the things that go to make up the product, not
just source code files. For example, the sources for the manuals are
here too, because we maintain them in parallel with the code.
The sources at Ravenbrook are mirrored from our Perforce server onto our
internal web server at info.ravenbrook.com, and are designed to be
browsed on that server. You will find HTML documents which index many
of the directories. Read these, starting with the top level
"index.html". You might find some links to "info.ravenbrook.com" or
"/project/p4dti/...". Sorry about that -- it's partly due to the nature
of HTML links. You will find most project documents from the P4DTI
Project page , including many
documents which aren't "sources" but may still be useful to understand
the history of the project.
4. DEVELOPING USING THE KIT
To set up the machine for development, follow the instructions at the
beginning of the P4DTI Administrator's Guide [RB 2000-08-10a] which
you'll find in "manual/ag/". The "Prerequisites" section will tell you
what software you need, and where to get it.
If you're doing TeamTrack work, you will also need Microsoft Visual C++
to build the Python TeamTrack interface and the TeamShare API. You need
to build "teamtrack.dll" first if you're developing the TeamTrack
integration. Use the "p4dti.dsw" file in the "code/".
Once your machine is set up, and you have a test defect tracker server
and a test Perforce server, configure the P4DTI as you would for
installation, following the instructions in the P4DTI Administrator's
Guide, updating the "config.py" file in "code/replicator/". Once this
is done, you should be able to sit in the "code/replicator" directory
and run the replicator from there using "python run.py". You can then
start modifying the code and testing your changes. You'll find some
example configurations in "test/".
When you change the code, be sure to change the documentation too. Keep
the manuals and the design documents up to date with your changes. We
do, and that's why they're useful to you. Please provide the same value
to others.
When you rename or move something, search the entire kit for occurrences
of that name, and update them. Cross references are very valuable, but
only if they work.
5. TESTING
Regularly run through all the use cases in the P4DTI User's Guide [RB
2000-08-10b] which you'll find in "manual/ug/". These use cases were
determined by research into what people really wanted to do with the
P4DTI, and will be maintained [GDR 2000-05-03]. Testing against them is
as close as you're likely to get to real use, at least as far as
functionality goes.
You'll find test materials, procedures, and programs in the "test/".
6. BUILDING AND TESTING A RELEASE
The release build procedure in "procedure/release-build/" describes how
we construct a product release of the P4DTI at Ravenbrook. Reading it
will help you to understand what goes into a product release, even if
you don't need to build one. You won't be able to follow the steps that
involve our Perforce repository.
The release test procedure in "procedure/release-test/" describes the
steps we take for every release we build. These include automatic
tests, but also a test of the installation and installation
instructions, and the use cases in the User's Guide. We recommend you
do likewise at regular intervals, even if you don't plan to redistribute
your version.
7. CONTRIBUTING YOUR WORK
We'd like to include new integrations in the P4DTI distributions from
Perforce Software. Please consider putting your work under an open
source license and sending it to Perforce.
It will help a great deal if your work is self-consistent. This means
that the documentation is up to date (even if only with sketchy but
accurate notes) and the procedures have been maintained.
8. GETTING HELP
See the "readme.txt" file for information about support for the P4DTI,
and about mailing lists you can join to discuss your work and get help
from others.
A. REFERENCES
[GDR 2000-05-03] "Requirements and use cases for Perforce/defect
tracking integration"; Gareth Rees; Ravenbrook Limited; 2000-05-03;
.
[GDR 2000-10-16] "Perforce Defect Tracking Integration Integrator's
Guide"; Gareth Rees; Ravenbrook Limited; 2000-10-16.
[RB 2000-08-10a] "Perforce Defect Tracking Integration Administrator's
Guide"; Richard Brooksby; Ravenbrook Limited; 2000-08-10.
[RB 2000-08-10b] "Perforce Defect Tracking Integration User's Guide";
Richard Brooksby; Ravenbrook Limited; 2000-08-10.
B. DOCUMENT HISTORY
2001-03-26 RB Drafted in e-mail.
2001-03-27 RB Formatted and added to sources.
---
This document is copyright (C) 2001 Perforce Software, Inc. All rights
reserved.
Redistribution and use of this document in any form, with or without
modification, is permitted provided that redistributions of this
document retain the above copyright notice, this condition and the
following disclaimer.
THIS DOCUMENT IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
DOCUMENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
$Id: //info.ravenbrook.com/project/p4dti/version/1.2/kit-readme.txt#1 $