This is the README documentation for the Perforce Defect Tracking Gateway
(P4DTG) Bugzilla plugin. This document is intended for new users and for users
who want an overview of the plugin.
If you are currently using P4DTI, see README.p4dti for details about migrating
from P4DTI to P4DTG. If you're a P4DTG SDK user, see README.src. For details
about using P4DTG, see the Perforce Defect Tracking Gateway User's Guide.
--------------------------------------------------------------------------------
The Bugzilla Plugin for P4DTG
This plugin mirrors fields between Bugzilla bugs and Perforce jobs. Although
bugs can be created only in Bugzilla, users can edit certain fields in the
corresponding Perforce job and have their changes mirrored in Bugzilla.
The plugin also associates fixes for those jobs with changelists and enables
them to be displayed in Bugzilla as links pointing to a P4Web instance, enabling
users to view change descriptions, diffs and other data.
System Requirements
-------------------
Architecture: x86
Operating systems:
Windows XP, 2003, Vista, 2008, 7
GNU/Linux 26
FreeBSD 6
Software versions:
Perforce server 2006.2+
MySQL 5.0+
Bugzilla 3.2.x, 3.4.x, 3.6.x and 4.0.x
Note on MySQL Client:
This plug-in for DTG uses the MySQL client library. The source for
this plug-in is available from ftp.perforce.com in the following directory:
perforce/RELEASE/linux26x86
This unsupported source distribution is licensed under the BSD license
of July 22, 1999.
To obtain the complete, supported P4DTG SDK for building new plug-ins,
email partners@perforce.com.
Choosing between P4DTI and P4DTG
--------------------------------
If you presently use P4DTI to replicate between Perforce and Bugzilla,
read the Perforce white paper "P4DTG or P4DTI? Choosing a Solution for
Integrating Perforce with Bugzilla". In general, if you are currently happy with
P4DTI, stay with it. If you are not already using P4DTI, use P4DTG.
--------------------------------------------------------------------------------
Configuring the Bugzilla plugin
To configure the plugin using the P4DTG configuration tool:
1. Click the "Defect Tracking Sources" tab.
2. Click "New".
3. From the "Type" dropdown list, choose the Bugzilla/MySQL option.
4. In the "Server connection details" fields, specify the login account details for
your MySQL server. The MySQL account must have SELECT, INSERT and UPDATE
privileges on the host P4DTG is running from and for the Bugzilla database.
5. To modify optional attributes, click "Edit attributes...".
The optional attributes are as follows:
"Bugzilla username"
If your Bugzilla user name is different from your MySQL user name, enter
it here. Account names are typically formatted like an email address.
"Fixes custom field"
The custom field where fix information is stored.
Important: If you change the default name of the custom
field, you must modify the patched Bugzilla code to reflect the
difference.
"MySQL database name"
The name of the Bugzilla database in the MySQL server.
"Unicode server"
Specifies whether the Bugzilla database uses and supports Unicode.
Starting with Bugzilla release 2.22, UTF-8 is the default encoding for
Bugzilla databases. To check your database, see the instructions for the "utf8"
field:
http://www.bugzilla.org/docs/3.0/html/parameters.html
"Wait time"
Number of seconds to wait on MySQL errors before retry. To configure
replication to quit when an error occurs, specify -1.
"Check privileges"
Specifies whether the plug-in checks the user's access rights to the MySQL
user before connecting.
"Change offset"
Configures a delay to ensure that heavily-loaded servers do not skip
records.
Heavy defect tracker activity can cause a delay between the time that
Bugzilla records in the ModifiedDate field and the time that the issue
is actually committed. This discrepancy might cause P4DTG Replication
Engine to skip issues. To minimize this possibility, set "Change offset"
to 30 seconds. To prevent Bugzilla defect data from overriding Perforce
Job data, minimize the number of mirror mappings when using this
setting.
6. Click "Check connection and retrieve fields". If your entries are correct,
the configuration tool displays "Valid connection to server".
After you've configured Bugzilla as a defect tracking source, configure your
Perforce Source and mappings as described in the P4DTG User Guide and online
help.
The Bugzilla plugin adds the following fields to the list of defect tracker
fields that are displayed in the Gateway Mappings dialog:
- Status/Resolution: combines the Status and Resolutions fields so
that they can be mirrored with the Perforce Status field. See the jobspec.txt
file for an example jobspec which would allow for mirroring with a standard
Bugzilla 3.2 or 4.0 installation. If the possible resolutions have been
altered for your site, update the possible status fields accordingly. The
sample jobspec requires a Perforce Server 2008.1 or later. For earlier
servers, specify change 'Closed-Fixed' on the Perforce jobspec to 'closed'
and alter the mirror mapping accordingly.
If you have defined additional 'closed' status values for your site ('closed'
status values are those which require a Resolution value), then list these
fields in the 'Added closed states' attribute for the Bugzilla DataSource
using the Configuration tool. You will need to expand the list of possible
Perforce status values to include these states. Note: All new values must
match the case as defined in Bugzilla.
- Product/Component: combines the Product and Component fields so
that they can be used for segmentation. For any field used in segmentation,
the bug should never change such that it changes out of an existing segment.
Bugs can migrate into a segment; but never out.
- Fixes: to append fix information to the Bugzilla bug "Comments" field, map
the Perforce "Fix Details" field to this field. You can specify details to
be appended, such as the changelist number or user who made the fix, etc.
- Description: the aggregate of the Bugzilla "Comments" field. To display this
information in the Job, map this field to a TEXT field in the Perforce job
specification.
--------------------------------------------------------------------------------
Optional Configuration Options
- To display a list of fixes associated with a bug:
Create the "cf_p4fixes" Bugzilla custom field in Bugzilla
as follows:
1. Log into Bugzilla using the administration account.
2. On the home page, click the "Administration" link.
3. Click the "Custom Fields" link.
4. Click "Add a new custom field".
5. In the "Name" field, type "cf_p4fixes".
6. In the "Type" dropdown, select "Large Text Box" or "Free Text".
7. In the "Description" field, type "Perforce fix information".
8. Click "Create".
This field is displayed in the Gateway Mappings dialog as "Perforce fix
information". To display a list of fixes associated with the bug, map
the "List of Change Numbers" field from Perforce to this field.
For more details, refer to the Bugzilla documentation.
- To enable display of P4Web links to bug fixes, apply the P4DTG Bugzilla patch
as follows:
1. In a shell window, change directories to the Bugzilla root directory.
2. Invoke the patch program (see References) as follows:
[/bugzilla] patch -b -p1 < /p4dtg/doc/bugz3mysql5/patch.bugzilla
The patch program displays output resembling the following:
patching file show_bug.cgi
patching file template/en/default/bug/field.html.tmpl
Specify the patch file that corresponds to your Bugzilla version.
3. Edit the "show_bug.cgi" file to ensure that the URL to your P4Web
instance is correct. If the URL ever changes, update this file. The URL
is not stored in the database. As you change the URL in the
source file, the new URL is in effect for all bugs.
4. To override the default name for the custom field, edit
"field.html.tmpl".
- To install the Perforce server trigger, follow the instructions at the top of
the trigger file: p4dtg/doc/bugz3mysql5/changeid.pl. The trigger implements
the following functionality:
- Prevent Perforce users from creating jobs. The Bugzilla plug-in does not
support originating jobs in Perforce.
- Prevent editing of read-only fields in Perforce. You can define one-way
mappings of read-only fields in Bugzilla to Perforce, and this trigger
prevents users from editing these fields. If users edit one of these
fields, any data they enter is overwritten with the field value in
Bugzilla during replication.
- Make the "Job" field match the Bugzilla bug number. Normally, jobs in
Perforce are named using "jobNNNNNN", where NNNNNN is an ever-increasing
number.
P4DTG's configuration tool prevents the mapping of Bugzilla workflow-
related fields from Perforce to Bugzilla. For example, the "Status" and
"Resolution" fields are read-only. This approach prevents replication of
these fields from Perforce to Bugzilla. Use the "Status/Resolution" field
to update these fields.
References
----------
Reference for the 'patch' utility. See 'external links' for downloads.
http://en.wikipedia.org/wiki/Patch_%28Unix%29