PERFORCE DEFECT TRACKING INTEGRATION README FOR RELEASE 0.3.3 Richard Brooksby, Ravenbrook Limited, 2000-10-19 1. INTRODUCTION This is an alpha release of the Perforce Defect Tracking Integration (P4DTI). The primary purpose of this release is to incorporate all changes made during the project alpha programme [RB 2000-11-04]. Ravenbrook and TeamShare staff visited selected sites to install and test the software, and gather feedback. Various changes were made to fix problems encountered (see appendix A for links to the defect reports). We do _not_ recommend that you install and run this software in your organization. The software is _not_ supported in any way by Ravenbrook, Perforce Software, or TeamShare. For up-to-date information about releases of the P4DTI, see the releases index . Reports of defects found in releases will be posted there. For general information about the project, see the project front page . The readership of this document is anyone who wants to download and use the Perforce Defect Tracking Integration. This document is not confidential. 2. SUPPORTED CONFIGURATIONS This release supports: - Perforce 2000.1 (with a special client available from Ravenbrook) on any platform; - TeamTrack internal build 4402 (available from Ravenbrook) running on Windows NT 4. It does not support Bugzilla. Instructions for obtaining the special Perforce client and internal TeamTrack build are included in the Administrator's Guide. Follow the instructions in the "Installation" section below. 3. INSTALLATION On the TeamTrack server machine, run the "p4dti-teamtrack-0.3.3.exe" installer program. 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. Then consult the Administrator's Guide (installed by default in "C:\Program Files\P4DTI\sag\index.html") for further instructions. 4. RELEASE NOTES 4.1. What's New Everything is new. This is the first release we're taking out into the world. See the project version plan for a specification of version 0.3, which this release is intended to meet. 4.2. What's Changed Here is a summary of the significant changes made since release 0.3.2, which was the first to be taken out into the world. Change 4034 on 2000/11/03 by gdr@gdr-quokka If a changelist doesn't exist, don't replicate it. This allows the replicator to cope when a pending changelist is renumbered. The replicator should probably also delete the changelist from TeamTrack, so some more work is needed here. Made replicator more forgiving when a job doesn't exist, by not insisting on the presence of a P4DTI-user field. This change should not be merged back, because it's really a change that hides genuine errors. Change 4033 on 2000/11/03 by gdr@gdr-quokka Write to the log when TeamTrack configuration tables like SELECTIONS and STATES are read, so that mysterious long pauses in replication can be diagnosed. Change 3997 on 2000/11/02 by gdr@gdr-quokka Corrected error message when the job returned by Perforce has the wrong name. Change 3996 on 2000/11/02 by gdr@gdr-quokka Normalise case of field names in the database (DBNAME field) when reading in the selections table. This is so that we won't be foiled by mixed-case database field names when we are referring to them with all uppercase in the code. This does need thought before we merge this, becuase it might be better not to presume that all the fields are uppercase. Change 3957 on 2000/11/01 by gdr@rb-mahi-cmserver Fixed some minor bugs in sending e-mail. When re-replication fails, report both the orginal error and the new error, so that problems with re-replication (such as the afore-mentioned bugs in sending e-mail) can be tracked down. Change 3956 on 2000/11/01 by gdr@rb-mahi-cmserver Use only the ISSUETYPE and ISSUEID when building the jobname for an issue, so that the jobnames correspond exactly with the case names in TeamTrack. This should have been in the local configuration, not in this file, but I'm leaving it here for the moment. When replicating a single-select field from Perforce to TeamTrack, treat (None) specially. Any single-select field can have this value if unassigned, which has ID 0 in the SELECTIONS table. Without this, replication of single-select fields will fail. Change 3944 on 2000/10/31 by gdr@gdr-grouse When replication from Perforce to the defect tracker fails, reset the job to a copy of the issue and e-mail the Perforce user who made the mistake. This is a very rough fix that needs work. Change 3822 on 2000/10/27 by gdr@gdr-grrr-installed When updating the action fields of the issue and job when the replicator discovers a conflict, it make sure it updates the issue/job as found in the database and not the copy it has in hand, which may have changed. This is probably not the best fix for this problem, but it's simple and quick for the alpha. Change 3821 on 2000/10/27 by gdr@gdr-grrr-installed If the issue status changed, don't update it if you can't find a transition. Raise an error instead. Change 3814 on 2000/10/27 by gdr@gdr-grrr-installed Added support for replication of single-select fields. Change 3783 on 2000/10/27 by gdr@gdr-grrr-installed Removed replication of changelists (it's too slow). Change 3695 on 2000/10/24 by gdr@gdr-derekpc Fixed bug discovered during alpha testing at TeamShare PSG. There's an assertion in the changed_cases() method that says roughly, "if there are no changes to cases then we don't have to look at any cases." BUT this isn't correct. There might be changes to fixes and filespecs that don't show up as changes to cases. So I've commented out the assertion. Change 3694 on 2000/10/24 by gdr@gdr-derekpc Fixed problems discovered during alpha testing at TeamShare PSG. See the e-mail "TeamShare PSG alpha test report, 2000-10-23". 1. Optional fields in Perforce jobspec don't appear when you get the job out of Perforce, so don't assume that they exist. 2. Non-existent users in TeamTrack get replicated to user '(None)' in Perforce. Change 3533 on 2000/10/19 by gdr@gdr-sandpiper New file migrate_teamtrack.py migrates jobs from Perforce to TeamTrack. It deliberately doesn't compile so that you have to check that the default values for the fields are correct. Change 3532 on 2000/10/19 by gdr@gdr-sandpiper Reformatted to make it [replicator_test.py] look more like config_teamtrack.py. (Perhaps it should be called config_teamtrack_sandpiper.py or something like that since it's my testing configuration for TeamTrack on sandpiper. Do we need a scheme for these things?) 5. KNOWN DEFECTS IMPORTANT: Read the defect reports in the releases index . You will find information about defects found _after_ release. There could be vital information there which we couldn't know when we wrote this document. If you don't read the document you might meet the same problems, waste a lot of time, and possibly DESTROY ALL YOUR DATA. This is a list of major defects which were known at the time of release. 6. GETTING SUPPORT Sorry, this alpha release isn't supported in any way by Ravenbrook Limited, Perforce Software, or TeamShare. We _are_ interested in your experiences if you decide to have a go. Please write to the addresses listed in the "Project Contacts" below. 7. PROJECT CONTACTS If you have questions about the project please write to . If you have a comment on the project, you can write to . You can also join the p4dti-discussion mailing list. The goals of the list are: 1. to provide feedback to the project on requirements, design, implementation, etc.; 2. to allow people to exchange information and experience with using and adapting the project; 3. to keep people informed about project progress. To join, send a message with the word "subscribe" in the _body_ to or send the word "help" for general information. Please note that the mailing list will be archived and the archive may be published. A. REFERENCES [GDR 2000-10-16] "Integration test report [for release 0.3.0]" (e-mail message); Gareth Rees; Ravenbrook Limited; 2000-10-16; . [GDR 2000-10-17a] "Test report for release 0.3.1" (e-mail message); Gareth Rees; Ravenbrook Limited; 2000-10-17; . [GDR 2000-10-17b] "Build report for release 0.3.1" (e-mail message); Gareth Rees; Ravenbrook Limited; 2000-10-17; . [RB 2000-10-18a] "Release 0.3.2 build report" (e-mail message); Richard Brooksby; Ravenbrook Limited; 2000-10-18; . [RB 2000-10-18b] "Test report for release 0.3.2" (e-mail message); Richard Brooksby; Ravenbrook Limited; 2000-10-18; . [GDR 2000-10-23] "TeamShare PSG alpha test report, 2000-10-23" (e-mail message); Gareth Rees; Ravenbrook Limited; 2000-10-23; . [RB 2000-10-24] "TeamShare PSG Alpha Test Report, 2000-10-24" (e-mail message); Richard Brooksby; Ravenbrook Limited; 2000-10-24; . [GDR 2000-10-26] "Alpha test report: Perforce, 2000-10-26" (e-mail message); Gareth Rees; Ravenbrook Limited; 2000-10-26; . [GDR 2000-10-27] "Alpha test report: Perforce, 2000-10-27" (e-mail message); Gareth Rees; Ravenbrook Limited; 2000-10-27; . [GDR 2000-10-30] "Mahi Networks alpha test notes, 2000-10-30" (e-mail message); Gareth Rees; Ravenbrook Limited; 2000-10-30; . [GDR 2000-10-31] "Alpha test report for Mahi Networks, 2000-10-31" (e-mail message); Gareth Rees; Ravenbrook Limited; 2000-10-31; . [GDR 2000-11-01] "Alpha test report for Quokka Sports, 2000-11-01" (e-mail message); Gareth Rees; Ravenbrook Limited; 2000-11-01; . [GDR 2000-11-03] "Alpha testing at Quokka, 2000-11-02" (e-mail message); Gareth Rees; Ravenbrook Limited; 2000-11-03; . [RB 2000-11-04] "Perforce Defect Tracking Integration Alpha Programme Report"; Richard Brooksby; Ravenbrook Limited; 2000-11-04; . B. DOCUMENT HISTORY 2000-10-19 RB Created using FreeBSD release documents as a model. 2000-11-08 RB Updated to explain purpose of release 0.3.3. Added references to reports. Improved instructions for obtaining special client and builds. Added a summary of changes. Added readership and confidentiality. --- 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/release/0.3.3/readme.txt#2 $