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.3/kit-readme.txt#1 $