MIGRATION FROM P4DTI TO P4DTG FOR BUGZILLA USERS -------------------------------------------------------------------------------- This document tells you how to migrate your P4DTI/Bugzilla integration to P4DTG, the Perforce Defect Tracking Gateway. Upgrading from P4DTI -------------------- Before converting, back up your Bugzilla, Perforce, MySQL and P4DTI data. To convert to P4DTG, you must be running version 2.4.2 of P4DTI. If you aren't running version 2.4.2, you must upgrade or verify that the "p4dti_fixes" table in the Bugzilla database matches the current release. See the appendix for further information on upgrading. To convert from P4DTI to P4DTG: 1. Upgrade to Bugzilla 3.2.x, 3.4.x, 3.6.x or 4.0.x Refer to the Bugzilla documentation for details. 2. *optional* Enable P4Web URLs inline on Bugzilla bug pages. Create the "cf_p4fixes" Bugzilla custom field in Bugzilla. Refer to the Bugzilla documentation for details. Likely steps: a. Log into Bugzilla with the administration account. b. Click on the "Administration" link off of the home page. c. Click on the "Custom Fields" link. d. Click on "Add a new custom field". e. In the "Name" field, enter "cf_p4fixes". f. In the "Type" dropdown, select "Large Text Box" or "Free Text". g. In the "Description" field, type "Perforce fix information". h. Click the "Create" button Apply the P4DTG Bugzilla patch to show P4Web URLs for fixes on bugs: In a shell window, change directories to the Bugzilla root directory, then invoke the patch script as follows: [/bugzilla] patch -b -p1 < /p4dtg/doc/bugz3mysql5/patch.bugzilla The patch program (see References) displays output resembling the following: patching file show_bug.cgi patching file template/en/default/bug/field.html.tmpl Note that you will need to select the patch file that matches your Bugzilla version. The URL to your P4Web instance is stored in the "show_bug.cgi" file. You must edit it to insert the correct data. If the URL ever changes, you must update this file. The URL is not stored in the database, so as soon as you change it in the source file, the change is active for all bugs. If you must use a non-default name for the custom field, you must edit "field.html.tmpl" accordingly. 3. To copy P4 fix information from the P4DTI database table to the new custom field, run the "dti_to_dtg.pl" script. Run this from the root directory of your Bugzilla installation. 4. Edit the Perforce jobspec as follows: Run "p4 jobspec" as the super user and add the following fields, adjusting the leading number as appropriate. 106 DTG_FIXES text 0 optional 107 DTG_DTISSUE word 32 optional 108 DTG_ERROR text 0 optional 109 DTG_MAPID word 32 optional The (optional) DTG_MAPID exists to support segmented replication. See the P4DTG user's guide for details. Change all existing P4DTI fields that are specified as "required" or "always" to "optional". 5. To copy the P4DTI bug ID field to the new DTG identifier, run the "mk_dtgissue.pl" script. It gets its server connection details from your environment. Set those up prior to running the script (P4PORT/P4USER/etc). The script makes use of the P4-Perl Perforce API. It is a required dependency. If you don't already have it installed, you can get it via Perforce.com->Downloads->"Related Software"->"Perforce Perl API". 6. Install the Perforce server jobs trigger. Here is an example of what this looks like in the server triggers table: Triggers: jc form-in job "/p4/triggers/changeid.pl %user% %formfile%" You'll need to edit the trigger script, configuring it as necessary. 7. Set the Perforce job counter to match the Bugzilla bug number. On the Perforce server, you can set the starting number for new job names. If you want new jobs to use numbers in a sequence higher than your bug numbers, such as "bug1234" going to "job1235", then do this: p4 counter -f job 1235 By default, P4DTG does not create jobs with names identical to the Bugzilla bug. This is to support users with multiple defect trackers, as there may be bug name conflicts between them. By allowing the Perforce server to assign its own numeric names to bugs, collisions are prevented. If you wish to have jobs created with the same name as the bug, then you may do so by configuring the "changeid.pl" script. Configuring P4DTG after converting from P4DTI --------------------------------------------- Beyond entering the appropriate connection details in the plugin, you should change the "Start replication from" field under "Gateway Mappings" to a date and time just after you stopped the old replicator. Follow the instructions in README.txt for configuring the rest of P4DTG. The *Optional* step above requires mapping the DTG "List of Change Numbers" field to the "Perforce fix information" field in Bugzilla. -------------------------------------------------------------------------------- Appendix Upgrading P4DTI --------------- Before upgrading to P4DTI version 2.4.2, remove the P4DTI patches to Bugzilla (if you're installing the new Bugzilla on top of your old version. Alternately, put the new Bugzilla in a different directory and skip this step.) Refer to the P4DTI documentation for specifics, but the upgrade process consists of the following steps: 1. Stop P4DTI and any cron jobs that restart it. 2. Invoke the patch script, for example: [/bugzilla-3] patch -p1 -R < /p4dti-bugzilla-2.4.2/bugzilla-3.0-patch The script output looks like this: patching file Bugzilla/Bug.pm patching file Bugzilla/Config/Core.pm patching file Bugzilla/Config.pm patching file template/en/default/admin/params/core.html.tmpl Hunk #1 succeeded at 108 (offset 1 line). References ---------- Perforce Defect Tracking Integration Administrator's Guide http://public.perforce.com/public/perforce/p4dti/release/2.4.2/ag/index.html Reference for the 'patch' utility. See 'external links' for downloads. http://en.wikipedia.org/wiki/Patch_%28Unix%29