Figure 1. The replication architecture
Perforce Defect Tracking Integration Project
This manual is the Perforce Defect Tracking Integration Administrator's Guide. It explains how to install, configure, maintain, and administer the Perforce Defect Tracking Integration (P4DTI).
The P4DTI connects your defect tracking system to Perforce, so that you don't have to switch between them and enter duplicate information about your work. It also links changes made in Perforce with defect tracker issues, making it easy to find out why a change was made, find the work that was done to resolve an issue, or generate reports relating issues to files or codelines. The P4DTI is intended to allow integrations with a number of different defect trackers. The only defect tracker supported by this release of the P4DTI is Bugzilla.
This document is intended for P4DTI administrators. Ordinary users of the defect tracker or Perforce should read the Perforce Defect Tracking Integration User's Guide. (For ideas on how to train your users on the P4DTI, see section 8, "Training and documentation".)
This guide does not describe the basics of using the P4DTI, Perforce, or the defect tracker. Read the Perforce Defect Tracking Integration User's Guide to understand the P4DTI from a user's perspective.
To install and run the P4DTI, you must:
The P4DTI works by taking over the job tracking system of Perforce and making the defect tracker's records appear as Perforce jobs. Perforce users can work with jobs more or less as described in the Perforce manuals, and their changes are reflected in the defect tracker. For more information on how Perforce handles jobs, see the Perforce User's Guide.
Perforce has a mechanism for linking jobs to changelists (the p4 fix command), to enable you to record the work done for a particular reason. The P4DTI makes these links appear in the defect tracker, making it easy to see what was done or is currently being done to resolve a defect.
The P4DTI replicator is a process that copies data between a defect tracker and a Perforce server to keep each one up to date with changes made in the other. This approach allows developers to do their routine defect resolution work entirely from their Perforce client, without using the defect tracker's interface. It also allows developers to relate their changes to defect tracking issues.
Figure 1 shows how the replicator communicates with the defect tracking server and the Perforce server.
The replicator maintains a one-to-one relationship between issues in the defect tracker's database and jobs in the Perforce repository. (An issue is a unit of work that the defect tracker tracks; some examples are bugs, change requests, and enhancement requests.) In other words, each issue has a corresponding job, and vice versa. The replicator keeps the contents of a configurable set of fields in the defect tracker's issues the same as the contents of the corresponding Perforce job, so that editing one edits the other.
The replicator also copies Perforce's links between jobs and changelists (called "fixes") to the defect tracker's database, and makes them visible in the defect tracker's user interface. Replication of links from Perforce to the defect tracker makes it possible to track, record, and check a number of things; in particular, it makes it possible to track and record the changes made for each issue, and find out why a change was made in terms of issues.
The replicator polls the defect tracking server and the Perforce server at regular intervals to get a list of recent changes, and attempts to propagate these changes to the other system. If a defect tracker issue is changed at the same time as the corresponding Perforce job, the replicator sends an e-mail with the overwritten Perforce job data to the following people:
Most defect trackers have an idea of workflow - a set of rules that control who can do what to which issues. The replicator enforces the defect tracker's workflow by rejecting changes to jobs in Perforce that are illegal in the defect tracker. When it comes across such a change, it undoes the change and sends an e-mail message to the user.
The defect tracker manages the defect tracker records (and therefore the job contents), while Perforce manages the changelists. Neither side controls the "fixes" relationship - the links between jobs and changelists.
Figure 1 shows how the replicator connects to the Perforce and defect tracker servers.
Figure 1. The replication architecture
The P4DTI won't work well for every organization. In particular, it has the following limitation:
If you have automation that makes very frequent changes to records in the defect tracker, then users may be unable to edit jobs from Perforce.
(This is because the P4DTI works by polling the databases every 10 seconds (by default). If there are many updates to the defect tracker in this period then the data in Perforce will be out of date; any attempt to edit out-of-date data is rejected by the P4DTI because that would introduce inconsistencies.)
To administer the P4DTI, you must have the following experience:
Before installing the P4DTI, you must obtain and install the following items:
You must also do the following:
It is possible to keep existing issues that are stored in Perforce jobs. A procedure called "migration" submits all the Perforce job data to the defect tracker, so that the issues can be replicated back to Perforce, and so appear in both systems. This requires more experience of Perforce and some Python programming. See section 4, "Migrating to the defect tracker from Perforce jobs", of the Perforce Defect Tracking Integration Advanced Administrator's Guide.
Before installing the P4DTI, you must do the following:
processmail script to promptly send e-mail to
Bugzilla users when bugs change.Lock_tables_priv
privilege and this privilege is required for the replicator to run.
This privilege must be granted to the user
that the replicator uses to log in to MySQL; this user is normally the
same as the Bugzilla MySQL user (which is normally bugs)
and is specified by
dbms_user in the configuration file.
For details of the MySQL privilege system, see the MySQL Reference
Manual. At the time of writing the privilege system is
described in 4.2 General
Security Issues and the MySQL Access Privilege System.
You must also obtain and install the following software:
| Name | Version | Download Location | Notes |
|---|---|---|---|
| Bugzilla | 2.14.4, 2.14.5, 2.16.1, 2.16.2, 2.16.3, or 2.16.4. |
<http://www.bugzilla.org/download.html> | Use of versions prior to 2.14.5 or 2.16.4 is deprecated. On Microsoft Windows, only 2.14.4 and 2.14.5 are supported. You must keep the Bugzilla database in MySQL 3.22.19 or later. Note: If you've changed your Bugzilla code, see section 5.3.1, "Patching Bugzilla" |
| Python | 1.5.2 or later | <http://www.python.org/download/> | On Microsoft Windows, you will require Python 2.0 or later. |
| MySQL-python | 0.2.2 to 0.9.2 | <http://sourceforge.net/projects/mysql-python> | The P4DTI will probably work with MySQL-python releases after 0.9.2, but this hasn't been tested |
| Python Windows extensions | 132 or later | <http://starship.python.net/crew/mhammond/win32/> | On Microsoft Windows only. You do not require this if you don't
plan to either log activity to the Windows Event Log (see the use_windows_event_log configuration
parameter) or run the P4DTI as a Windows service (see section 5.5.2) |
You must ensure that the P4DTI can work out how users in the defect tracker correspond to users in Perforce, as follows:
Create a Bugzilla account for every Perforce user.
Make sure that each user has the same e-mail address in Bugzilla and in Perforce. The P4DTI uses e-mail address to match up users between the two systems.
The P4DTI supports Bugzilla's "emailsuffix" feature (once you've applied the Bugzilla patch, section 5.3.1, and turned on the P4DTI extensions in Bugzilla, section 5.3.3), so if you have "emailsuffix" set to "@company.domain", then the user "joe" in Bugzilla will match a user in Perforce with the e-mail address "joe@company.domain".
There are several problems that can occur if the P4DTI can't match up users properly:
To help you prevent these problems, each time you start the P4DTI it sends an e-mail message to the administrator containing a report listing the unmatched and duplicate users. An example report is shown in figure 5. Read reports you receive and fix the problems.
Figure 5. Example e-mail sent when the P4DTI starts.
|
Notes on figure 5:
Headers: The e-mail message is addressed to the
administrator_address, and sent from the replicator_address.
Section 2 lists Perforce users that couldn't be matched to a user in the defect tracker (here Bugzilla). Here the users haven't set their e-mail addresses in Perforce: they still have the defaults.
Section 3 lists defect tracker users that couldn't be matched to a user in Perforce.
Section 4 lists Perforce users with duplicate e-mail addresses. In this case, if a Bugzilla user had the address <ndl@company.domain> then the P4DTI may have matched them wrongly. Give each Perforce user a distinct e-mail address.
Section 5 lists Bugzilla users with duplicate e-mail addresses, when converted to lower-case. Give each Bugzilla user a distinct, case-insensitive e-mail address.
Note: You might want to practice installing and configuring the P4DTI using a test Perforce repository and a test defect tracking database before you try it with your real data. A copy of your real Perforce repository would be ideal; for instructions on how to make a copy of your repository, see the Perforce System Administrator's Guide.
The P4DTI can be installed on any machine that can communicate with the defect tracker's server and the Perforce server. To keep administration simple and reduce network traffic, install and run the P4DTI on the same machine as the defect tracker's server. The rest of this manual assumes that you do this.
Use directory permissions to prevent the P4DTI directory from being read by other users. This will prevent users from reading passwords and any other sensitive information used or accessed by the P4DTI.
For instructions on how to upgrade from an earlier version of the P4DTI, see the readme.txt file.
The P4DTI is distributed as a self-extracting executable called p4dti-DT-RELEASE.exe (where DT is the defect tracker, such as "bugzilla", and RELEASE is the release number, such as "2.0.3").
To install the P4DTI, run this executable on the machine where the defect tracker server is installed. The installer unpacks the P4DTI into C:\Program Files\P4DTI-RELEASE\ by default.
The P4DTI is distributed as an RPM called p4dti-RELEASE-1.i386.rpm where DT is the defect tracker, such as "bugzilla", and RELEASE is the release number, such as "2.0.3").
To install the P4DTI, run the following command as root on the defect tracker server machine:
rpm -i p4dti-RELEASE-1.i386.rpm This installs the P4DTI files into /opt/p4dti and a startup script in the /etc/rc.d/init.d directory.
If you prefer not to use RPMs, you can follow the procedure in section 4.4, "Solaris installation".
The P4DTI is distributed as a gzipped tar file called p4dti-DT-RELEASE.tar.gz (where DT is the defect tracker, such as "bugzilla", and RELEASE is the release number, such as "2.0.3").
To install the P4DTI, unpack this tar file on the defect tracker server machine, using the following command:
gunzip -c p4dti-DT-RELEASE.tar.gz | tar xvf -You must determine where to put the files. You can put the files wherever you want.
Work through the subsections in the order in which they appear. Do not attempt to run the P4DTI until you have reached the end of this section, or you might end up with a non-working installation.
To configure the P4DTI with Perforce and your defect tracker, you must:
To configure the P4DTI, you edit definitions of Python variables in the file config.py in the installation directory. Edit these definitions according to the notes below. All variables in the file must have a value.
dt_nameDescription: The name of the defect tracking system you're integrating with.
Example: "Bugzilla"
Past versions of the P4DTI supported integrations with other defect trackers (e.g. TeamTrack). Future versions of the P4DTI may also do so.
administrator_address Description: The e-mail address of the P4DTI administrator.
Example: "p4dti-admin@company.domain"
The replicator sends error reports to this address. If this is
None, then the replicator never sends
e-mail.
p4_port Description: The address and port of the Perforce server with which the replicator communicates.
Example: "perforce.company.domain:1666"
p4_user Description: The userid that the replicator uses to log in to the Perforce server.
Example: "p4dti-replicator0"
For information about how the replicator logs in to Perforce, see section 5.2, "Perforce configuration". If you want to add more replicators later, incorporate the replicator identifier (rid) into this userid.
p4_password Description: The password the replicator uses to log in to the Perforce server. If there is no password, specify "" (empty quotes).
Example: ""
For information about how the replicator logs in to Perforce, see section 5.2, "Perforce configuration".
replicator_address Description: The e-mail address from which the replicator sends e-mail. This address is used in the "From" field of e-mail that the replicator sends.
Example: "p4dti-replicator0@company.domain"
To make it easier for users to get assistance, make this address an alias for the administrator e-mail address (administrator_address). This e-mail address is also used for the replicator's Bugzilla account; see section 5.3.2, "Creating a Bugzilla user for the replicator".
smtp_server Description: The address of the SMTP server that the replicator uses to send e-mail.
Example: "smtp.company.domain"
If this is None, then the replicator
never sends e-mail.
If you need to run the P4DTI without being connected to a network (for
example, if you want to set it up on a laptop so that you can give a
demonstration), set smtp_server=None so
that the replicator doesn't try to send e-mail.
start_date Description: The starting point in time for replication.
Example: "2002-02-10 00:00:00"
Issues modified after this date are replicated; issues unchanged
after this date are ignored. Must be a string in the form "YYYY-MM-DD HH:MM:SS".
closed_state Description: The Bugzilla state that maps to the "closed" state in Perforce. Specify None if you want the ordinary state mapping rules to apply.
(Note that you must write None
literally, not the string "None", which
would mean the state called "None").
Example: "RESOLVED".
Mapping the defect tracker state that developers use most often to
the "closed" state in Perforce makes using the P4DTI easier for the developers,
because the Perforce user interfaces make it easier to fix a job to
"closed" than any other state. If you specify a closed_state then the "CLOSED" state in Bugzilla
maps to "bugzilla_closed" in Perforce.
replicated_fields Description: A list of the names of Bugzilla fields that are
replicated in Perforce. Do not include the fields "bug_status",
"short_desc", "assigned_to" or "resolution": they are always
replicated anyway (unless included in omitted_fields).
Example: ["longdesc", "priority", "bug_severity", "product"]
For advice on which fields to replicate, see section 5.1.5, "Choosing which fields to replicate".
omitted_fieldsDescription: A list of the names of Bugzilla fields that are not replicated in Perforce. The P4DTI will ordinarily replicate the fields "bug_status", "short_desc", "assigned_to" and "resolution". Leave this list empty if you want all those fields to be replicated. To prevent one or more of those fields from being replicated, include them in this variable.
Example: ["resolution"]
For advice on which fields to replicate, see section 5.1.5, "Choosing which fields to replicate".
field_namesDescription: A list specifying the names to give to Bugzilla fields when replicating them into Perforce. The P4DTI will automatically give names to replicated fields. You can use this variable to over-ride that automatic naming. Each entry in the list is a pair of a Bugzilla field name and a Perforce field name.
Example: [("assigned_to", "User"), ("status_whiteboard", "Whiteboard")]
For advice on which fields to replicate, see section 5.1.5, "Choosing which fields to replicate".
dbms_host Description: The host on which the Bugzilla MySQL server is running.
Example: "localhost"
Set this value to "localhost" if the P4DTI and the Bugzilla MySQL server run on the same machine.
dbms_port Description: The port number on the database host (dbms_host), on which the Bugzilla MySQL server
listens.
Example: 3306
MySQL normally listens on port 3306. Change this setting only if you have set up MySQL differently. Note that this parameter is expressed as a number, not as a string.
dbms_database Description: The name of the MySQL database in which Bugzilla stores its data.
Example: "bugs"
Normally set to "bugs" during Bugzilla
installation. Change this setting only if you have set up Bugzilla
differently.
dbms_user Description: The user name that the replicator uses to log in to MySQL to use the Bugzilla database.
Example: "bugs"
Bugzilla normally logs in to MySQL as user "bugs". Change this setting only if you have configured Bugzilla differently, or if you want to set up the replicator to log in as a different user.
dbms_password Description: The password that the replicator uses to log in to MySQL to use the Bugzilla database.
Example: ""
The default Bugzilla configuration logs in to MySQL with no password. Change this setting if you have configured Bugzilla differently, or you want to set up the replicator to log in as a different user and use a password.
bugzilla_directory Description: The directory in which Bugzilla is installed, or
None if you don't want the P4DTI to
generate Bugzilla change e-mail.
Example: "/home/httpd/html/bugzilla"
Bugzilla sends e-mail to its users when it notices that a bug has been changed. If the P4DTI is running on the Bugzilla server, it is able to use Bugzilla's processmail script to promptly send e-mail in the same way. This configuration parameter allows the P4DTI to locate processmail. Set it to None if the P4DTI is not running on the Bugzilla server or if you don't want the P4DTI to send these e-mail messages.
These parameters support advanced or rarely-used features. Most organizations can leave these parameters at their default values, at least to start with, and then set them later if necessary.
changelist_url Description: A format string used to build a URL for a changelist.
Specify None if there are no URLs for
changelists.
This is used by the defect tracker to provide a link from a fix to a web page providing more information about the changelist that fixed the issue. Figure 6 shows how this works in Bugzilla.
The value must be a format string valid for passing to sprintf(); it must have one %d format specifier, for which the change number
is substituted. (Note that because the value gets passed to sprintf(), you must double other percent signs.)
In order to use this feature, you must have a web application that can provide information about changelists. Applications suitable for this include:
P4Web. To allow any user to follow the link from the defect tracker to P4Web, you need to run it in "browse mode". See the P4Web documentation for details.
For P4Web, set changelist_url to
something like "http://info.company.domain:8080/%d?ac=10".
Perfbrowse.
For Perfbrowse, set changelist_url to
something like "http://info.company.domain/cgi/perfbrowse.cgi?@describe+%d".
Figure 6. Effect of changelist_url and job_url
job_url Description: A format string used to build a URL for job descriptions. Specify None if there is no URL for job descriptions.
This is used by the defect tracker to provide a link from an issue to a web page providing more information about the job that corresponds to the issue. Figure 6 shows how this works in Bugzilla.
Example: "http://info.company.domain/cgi/perfbrowse.cgi?@job+%s"
The string is a format string valid for passing to sprintf(); it must have one %s format specifier, for which the job name is substituted. (Note that because it gets passed to sprintf(), you must double other percent signs.)
keep_jobspec Description: The P4DTI will overwrite the existing Perforce jobspec, unless this is set to 1.
Example: 1
For more information, see section 5.2.3, "Handle Perforce jobs and jobspec".
log_file Description: The name of the replicator's log file. If None, messages aren't logged to any file. (Note
that you must write None literally, not the
string "None", which would mean the file
called "None").
Example: "C:\\Program Files\\P4DTI-RELEASE\\p4dti.log"
The replicator generates log messages to record its actions. These log messages are sent to all of the following locations:
use_system_log is 1). use_windows_event_log is 1). log_file configuration parameter (unless it's None). log_level Description: The minimum priority level of messages to log. Messages with this priority or a higher priority appear in the replicator's log.
Example: message.INFO
This parameter must be one of these constants:
message.ERR |
Errors. |
message.WARNING |
Warnings; that is, features of your system that the replicator can work around, but which you should pay attention to. For example, "Bugzilla configuration parameter 'p4dti' is turned off. You won't see Perforce fixes in Bugzilla until you turn it on. See section 5.3.3 of the P4DTI Administrator's Guide.". |
message.NOTICE |
Significant but expected events. For example, "Job 'bug37' overwritten by issue 37". |
message.INFO |
Informational messages. For example, "Replicating issue '37' to job 'bug37'." |
message.DEBUG |
Debugging messages. For example, "Perforce command: 'p4 -G -u p4dti-replicator0 -p perforce:1666 job -o bug37'." |
p4_client_executable Description: The location of the Perforce client executable.
Example: "C:\\Program Files\\Perforce\\p4.exe"
This setting doesn't need to be an absolute path name if the directory is on the replicator user's path. On Windows this setting might be "C:\\Program Files\\Perforce\\p4.exe". On UNIX it might be just "p4".
The client executable named by this parameter must be of version
2000.2 or later (run the command p4 -V to
check the client version), and it must be the same version as the
Perforce server you are connecting to. If there's a mismatch between
the Perforce client executable and the Perforce server, then you might
see the error message (P4DTI-7087)
Value for field 'Options' must be one of ....
p4_config_file Description: The name of a Perforce client configuration file that the replicator will attempt to create and use.
Example: "p4config"
If this variable is set, the replicator creates a file with this
name to store the Perforce user
password, and protects that file against reading by other users.
The P4CONFIG environment variable is used
to tell the Perforce client to obtain the password from this file.
The file is overwritten if it already exists. The replicator
must have sufficient file access permissions to create the file.
If this variable is not set, or is set to an empty string, the Perforce user password is passed to the Perforce client on the command line. Other users of the P4DTI server may be able to read the password from such a command line using tools such as "ps".
p4_server_description Description: A description of the Perforce server. This might be used by the defect tracker to show which Perforce server an issue is replicated to.
Example: "Hardware development group Perforce server"
poll_period Description: The period of time between the end of one poll of the servers and the start of the next, in seconds.
Example: 10
prepare_issue(issue, job) Description: A function that prepares a new issue for submission to the defect tracker by providing values for all the required fields.
See section 3, "Allowing users to create issues in Perforce" in the Perforce Defect Tracking Advanced Administrator's Guide for the full details.
replicate_p(issue) Description: A function that selects which issues to start
replicating. Normally, the P4DTI replicates all issues created or modified
after the start_date, but you can modify this
function to further restrict the issues.
See section 2, "Select the issues to replicate" in the Perforce Defect Tracking Advanced Administrator's Guide for the full details.
replicate_job_p(job) Description: A function that selects which jobs in Perforce to replicate. Normally, the P4DTI ignores jobs created in Perforce, but you can provide this function to allow users to create jobs in Perforce and have them replicated to the defect tracker.
See section 3, "Allowing users to create issues in Perforce" in the Perforce Defect Tracking Advanced Administrator's Guide for the full details.
rid Description: The replicator identifier.
Example: "replicator0"
Must be 32 characters or less, start with a letter or underscore, and consist only of letters, numbers, and underscores.
The replicator identifier is used to distinguish between replicators when multiple replicators are being used to replicate issues from a defect tracker to different Perforce servers. If you have only one replicator, it doesn't matter what you use for the replicator identifier; "replicator0" is a good choice since it allows you to add more replicators later.
If you change the replicator identifier then your currently replicated defect tracker issues stop being replicated. The replicator believes they are being handled by another replicator.
sid Description: The Perforce server identifier.
Example: "perforce0"
Must be 32 characters or less, start with a letter or underscore, and consist only of letters, numbers and underscores. You might want to use the hostname of your Perforce server, if it is stable.
use_perforce_jobnames Description: Determines whether the replicator uses Perforce-style jobnames.
If this parameter is 1, the P4DTI lets Perforce choose the names of the jobs it creates when replicating issues from the defect tracker (so jobs will be named job000001, job000002 and so on). This means that the job name won't match the name of the corresponding issue in the defect tracker.
If this parameter is 0 (the default), the P4DTI tries to match the defect tracker's names for the issues it replicates. In the Bugzilla integration, jobs are called bug1, bug2, and so on.
Example: 1
If you change this setting, the P4DTI doesn't rename existing jobs, but new jobs get the style of name you requested.
use_windows_event_log (Windows only)
Description: The replicator logs activity to the Windows event log if (and only if) this is 1.
Example: 1
If you set this to 1, you must make sure to install the Python interface to Windows (see section 3.3, "Bugzilla prerequisites").
Regardless of the setting of this parameter, the replicator also
logs activity to to the standard output and to the log file (log_file).
The replicator can generate very many log messages. So if you set
this parameter to 1, either specify "Overwrite events as needed" in the
Windows Event Viewer on the machine running the replicator, or else set
the log_level to a restrictive value like message.LOG_WARNING.
use_system_log (Unix/Linux only).
Description: The replicator logs activity to the Unix or Linux system log (syslog) if (and only if) this is 1.
Example: 1
Regardless of the setting of this parameter, the replicator also
logs activity to to the standard output and to the log file (log_file).
Choose which fields to replicate by setting the configuration
parameters replicated_fields and omitted_fields. Choose what to call these
fields in the Perforce jobspec by setting field_names.
Here's some advice on which fields to replicate:
FIX_DESCRIPTION field for
developers to explain what they did. Now that you're running the
P4DTI, you
don't need that field - you can look in the change comments of the
associated changelists to find out what the developer did - so leave
it out. For Bugzilla, you might want to replicate some of the following fields:
For Bugzilla, the replicator rejects the following types of changes from within Perforce:
The following table shows the translation between Bugzilla fields
and Perforce fields. If you have modified Bugzilla, your Bugzilla
field names may differ. To display the set of Bugzilla field names,
type mysqlshow bugs bugs at a shell
prompt. To change the name of a field in Perforce, set the field_names parameter.
Table 2. Bugzilla field names
| Bugzilla Field name | Name on Bugzilla form | Default name in Perforce | Replication policy |
|---|---|---|---|
| Fields always replicated | |||
| bug_id | Bug # | P4DTI-issue-id | read only |
Fields replicated unless in omitted_fields |
|||
| bug_status | Status | Status | read/write |
| assigned_to | Assigned To | Assigned_To | read/write, user |
| short_desc | Summary | Summary | read/write |
| resolution | Resolution | Resolution | read/write |
Fields only replicated if in replicated_fields |
|||
| bug_file_loc | URL | URL | read/write |
| bug_severity | Severity | Severity | read/write |
| op_sys | OS | OS | read/write |
| priority | Priority | Priority | read/write |
| rep_platform | Platform | Platform | read/write |
| reporter | Reporter | Reporter | read/write, user |
| qa_contact | QA Contact | QA_Contact | read/write, user or None |
| status_whiteboard | Status Whiteboard | StatusWhiteboard | read/write |
| reporter_accessible | Reporter checkbox | Reporter_accessible | read/write |
| assignee_accessible | Assignee checkbox | Assignee_accessible | read/write |
| qacontact_accessible | QA Contact checkbox | QAContact_accessible | read/write |
| cclist_accessible | CC List checkbox | CCList_accessible | read/write |
| longdesc | Description | Description | append only |
| bug_id | Bug # | Bug_number | read only |
| groupset | - | Groupset | read only |
| creation_ts | Opened | Creation_Timestamp | read only |
| delta_ts | - | Update_Timestamp | read only |
| product | Product | Product | read only |
| version | Version | Version | read only |
| component | Component | Component | read only |
| target_milestone | Target Milestone | TargetMilestone | read only |
| votes | Votes | Votes | read only |
| keywords | Keywords | Keywords | read only |
| lastdiffed | - | LastDiffed | read only |
| everconfirmed | - | EverConfirmed | read only |
The following fields are displayed on the Bugzilla bug form but are kept in separate database tables and cannot be replicated:
If you need to change the list of replicated fields after you've started using the P4DTI, see section 9, "Maintaining the P4DTI".
To configure Perforce, you must:
Create a user in Perforce for the replicator; for instructions, see the Perforce System Administrator's Guide. The replicator user must have the following properties:
The userid must be the same as the replicator Perforce userid (p4_user) that you specified in the P4DTI configuration.
The e-mail address must match the replicator e-mail address (replicator_address).
If you're using the Perforce protections, make the replicator an 'admin' or 'super' user so that it can set the jobspec. For instructions, see the Perforce System Administrator's Guide. You'll need to add a line like
admin user p4dti-replicator0 * //...to the protections list. Note: once you have a working jobspec, this privilege can be dropped. See also section 5.2.3, "Handle Perforce jobs and jobspec".
For information on getting a license from Perforce Software for this extra user, see section 3.2, "Perforce prerequisites".
You can use the P4DTI in combination with a Perforce trigger to enforce extra workflow restrictions. For example, if your organization assigns priorities to issues, you can prevent changes being made to areas of the repository unless they resolve at least one defect of priority 3 or higher.
The P4DTI comes with an example trigger script that you can adapt for your needs, installed as example_trigger.py in the default installation directory.
To enforce workflow restrictions, follow these steps:
replicated_fields configuration parameter. The P4DTI ordinarily takes over the Perforce jobs
system entirely, rewriting the jobspec based on the replicated_fields, omitted_fields, and field_names parameters. The resulting jobspec
will probably conflict with any existing jobs. You can configure the
P4DTI to
migrate existing jobs to the defect tracker instead, and/or to retain
or modify your existing jobspec.
If you do not have any Perforce jobs, or a jobspec which you wish to retain, you should skip this section.
If you do have Perforce jobs, but do not wish to retain either the jobs or your jobspec, you should delete the jobs and skip the rest of this section. For instructions on deleting jobs, see the Perforce User's Guide.
If you have jobs which you want to keep, you should do one of the following:
If you want to keep your jobspec (for instance, if you have
existing jobs or tools which depend upon it), you should set the keep_jobspec option to 1. That will prevent
the P4DTI from overwriting the jobspec. However, your jobspec will
probably not support the P4DTI, which requires a number of
P4DTI-specific fields (for instance, P4DTI-rid). You should check your jobspec, and
may wish to extend it. The rest of this section explains how to do
that.
To find out whether your current jobspec will support P4DTI
operation, including replicating the fields which you have specified,
run the command python check_jobspec.py
in the P4DTI
installation directory. A number of warning messages may be
generated, indicating potential problems with particular fields. For
instance, a field type may be incorrect, or a field may be missing.
If the jobspec cannot support P4DTI operation, these warnings will be
followed by an error message. For instance, if a field is missing
entirely, or if a field's specification is completely incompatible
with the data which the P4DTI expects to replicate for that field.
Note that check_jobspec.py will
not make any change to your jobspec.
Problems reported by check_jobspec.py
may be fixed manually or with the extend_jobspec.py script. To extend your
current jobspec by adding the fields required by the P4DTI, run the
command python extend_jobspec.py in the
P4DTI
installation directory. Note that this will only add fields
to the jobspec: it will not delete, renumber, or change existing
fields, although it will produce a warning if the specification of a
field may cause replication problems.
To change your current jobspec by adding required fields and also
changing the specification of existing fields to match fields in
Bugzilla, run the command python
extend_jobspec.py --force in the P4DTI installation directory. Note that
this will not delete or renumber any jobspec field.
To configure Bugzilla, you must:
You need to make some minor modifications to the Bugzilla code so that users can see Perforce information on Bugzilla bug forms, and so that the P4DTI can access the values of Bugzilla configuration parameters. These modifications are distributed as patch files for the supported versions of Bugzilla.
The patch utility distributed with some versions of Solaris can not handle the form of patch file distributed with the P4DTI. We recommend using the GNU patch utility.
Microsoft Windows does not come with a patch utility. Various packages of utilities for Microsoft Windows include one. If you do not have a patch utility, you can download version 2.5 of GNU patch, compiled for Windows, from <http://www.ravenbrook.com/project/p4dti/import/2001-11-13/UnxUtils/UnxUtils/usr/local/wbin/patch.exe>. This is distributed as part of the UnxUtils package under the GNU General Public License from <http://unxutils.sourceforge.net/>.
If you have modified Bugzilla at your site, you might still be able to apply the patch successfully. Changes to the database schema, the permissions rules, or the workflow rules are likely to cause the P4DTI to malfunction. You might need to modify the P4DTI if you have changed these parts of Bugzilla.
The patch for all Bugzilla versions changes the following Bugzilla files:
bug_form.pl, adding a Perforce
section to the bug form. defparams.pl, adding a parameter to
control whether or not the Perforce section appears. doeditparams.cgi, creating and
maintaining a database table containing Bugzilla's configuration
parameters. The patches for Bugzilla 2.14.4 and 2.14.5 also change this file:
globals.pl, deleting unsafe
environment variables so that the processmail script can be run by the P4DTI. The patches for Bugzilla 2.16.1, 2.16.2, 2.16.3, and 2.16.4 also add this file:
template/en/custom/bug/edit.html.tmpl,
adding the Perforce section to the bug form template. These changes are small and self-contained. If your changes do not affect these files or only affect them in minor ways, the patch should operate correctly. If the patch program fails because of your Bugzilla modifications, it might still be possible to introduce the changes by hand. If you cannot apply the patch, the replicator might still work, but the extensions listed in section 5.3.3 will not be available.
To apply the patch, follow these steps:
patch -p1 < p4dti-install-dir/bugzilla-bugzilla-version-patch
(where p4dti-install-dir is your P4DTI installation directory) and
bugzilla-version is your version of Bugzilla (2.14.4, 2.14.5,
2.16.1, 2.16.2, 2.16.3, or 2.16.4).You need to create a Bugzilla user for the replicator. The replicator uses e-mail addresses to work out which Perforce user corresponds to which Bugzilla user. A Perforce user that does not correspond to a Bugzilla user is translated to the replicator's Bugzilla user, except for user fields (for example, "AssignedTo") in jobs. The replicator rejects a change when there is no Bugzilla user corresponding to a changed user field.
To create a Bugzilla user for the replicator, follow these steps:
replicator_address). After patching the Bugzilla code, you need to enable the P4DTI extensions in Bugzilla. There are two extensions:
Bugzilla's bug form includes information about the corresponding job in Perforce, and a table of fixes.
Bugzilla saves its configuration parameters in its database, making it possible for the P4DTI to support the "emailsuffix" feature.
To enable the extensions, follow these steps:
To disable the Perforce section in the Bugzilla bug form, set the "p4dti" parameter to "off". Note that this does not control the replicator; it merely affects the display of replicated information.
To start the replicator, follow these steps from the operating system command line:
python run.py. The first time you start the replicator, it displays log output explaining how the replicator is connecting to the defect tracker, as shown in the following figure:
Figure 10. Example replicator log output on startup (Bugzilla integration)
2003-01-10 16:01:47 UTC (P4DTI-10070) MySQLdb version '0.9.1' (release '0.9.1') detected. This release is supported by the P4DTI. 2003-01-10 16:01:47 UTC (P4DTI-1251) Bugzilla version 2.14 detected. 2003-01-10 16:01:49 UTC (P4DTI-8002) Mailing 'P4DTI administrator <nb+admin@company.domain>'. 2003-01-10 16:01:49 UTC (P4DTI-8669) The P4DTI replicator has started. ... |
Each log entry consists of the date of the entry, a message identifier, and the message text. You can use the message identifier of an error message to look it up in section 11.2, "Error messages by identifier".
During its startup sequence, the replicator creates Perforce jobs corresponding to every defect tracker issue created or modified after the (start_date). It then polls for changes every poll_period seconds and replicates those changes. Figure 11 shows typical replicator log output when it is replicating a change.
Figure 11. Example replicator log output on replication (Bugzilla integration)
2003-01-10 16:01:52 UTC (P4DTI-8046) Replicating issue '4' to job 'bug4'.
2003-01-10 16:01:52 UTC (P4DTI-8126) -- Changed fields: {'Status': 'assigned', 'Priority': 'P5', 'Assigned_To': 'ndl@company.domain'}.
|
To stop the replicator on Windows, follow these steps:
poll_period seconds). To stop the replicator on Unix systems, kill the
replicator process. If it's running in a shell, bring it to the
foreground and type Control-C. If not, find out the process id of the
replicator process and run the command kill -TERM
replicator-process-id.
The P4DTI can be run as a daemon on Unix and as an NT service on Windows. Check that the replicator starts manually and runs correctly, before leaving it to run automatically.
If you installed the P4DTI using the Linux RPM as described in section 4.3, "Linux installation", a startup script is automatically created in /etc/rc.d/init.d directory, so that the replicator starts as a daemon when the machine is booted. Alternatively you can start the P4DTI daemon manually by calling the startup script yourself:
/etc/rc.d/init.d/p4dti startThe replicator halts automatically when the system is shut down. You can stop the replicator daemon manually using the stop script:
/etc/rc.d/init.d/p4dti stop On Solaris or other Unixes (and on Linux if you did not use the RPM installer), you might want to adapt the Linux startup script. It is in the file named startup-script in the installation directory.
On Windows, you can choose to install the P4DTI as a service. The replicator then starts when the machine is booted. You need not be logged on to the machine for the service to run or to stay running.
To install the service, follow these steps from the operating system command line:
python service.pyOnce the service has been installed, it can be started in any of the following ways:
python service.py start.Once the service is running, it can be halted in any of the following ways. Note that you need not halt the service the same way that you started it.
python service.py stop.To uninstall the service, go to the P4DTI installation directory and run the command:
python service.py removeNot all of the flexibility of the P4DTI is available using the configuration options described in this section. Advanced configuration of the P4DTI is possible, but beyond the scope of this manual. Here are some of the things that are possible with advanced configuration:
Contact Perforce technical support if you need any of these facilities.
You do not need to take any special action to migrate defect tracking data from your defect tracker to the integrated system. The replicator starts replicating defect tracker issues as soon as it starts up. Only issues that are created or modified after the start_date are replicated to Perforce.
See section 3, "Allowing users to create issues in Perforce" in the Perforce Defect Tracking Advanced Administrator's Guide.
See section 4, "Migrating to the defect tracker from Perforce jobs" in the Perforce Defect Tracking Advanced Administrator's Guide.
When you're testing your P4DTI configuration, you might need to tell the P4DTI take a single step; that is, to poll the defect tracker and Perforce for changes, replicate those changes, then stop. If you need to do this:
python poll.py. Test the P4DTI configuration by creating a test issue and taking it through a complete life-cycle (that is, through the workflow) as described in the Perforce Defect Tracking Integration User's Guide. You might need to adapt the use cases described in the user's guide to your organization's workflow.
Test the P4DTI from both Perforce and the defect tracker. In Perforce, test the P4DTI using the interface that your developers are most likely to use. The main Perforce interfaces are:
To run the consistency checker and manage its output, follow these steps:
python check.py. You can also examine the defect tracker's database using a database client application (for example the mysql command) to ensure the Perforce data is in there.
You might want to provide training for Perforce and defect tracker users before they adopt the P4DTI for everyday use. If so, consider preparing training materials that walk them through the workflow for an issue, using the procedures that are documented in the Perforce Defect Tracking Integration User's Guide.
Even if you don't have a formal training session for your users, ensure that they:
You must stop and restart the replicator as described in section 5.4, "Starting the replicator manually" after changing any of the configuration parameters described in section 5.1, "P4DTI configuration".
You must also refresh Perforce jobs, as described in section 9.2, "Refreshing jobs in Perforce", after changing:
replicated_fields);
or omitted_fields);
or field_names); or start_date). Perforce uses the field number in the jobspec to find data, not the field name (for more information, see the Perforce System Administrator's Guide). If you change the replicated fields, then the field numbers may change, which means that the fields of existing jobs in Perforce will be mixed up. Refreshing the jobs re-creates them from the defect tracker with the correct fields.
If you want finer control over your jobspec, set the keep_jobspec parameter to 1. This allows
you to set your own jobspec (with p4
jobspec) which the P4DTI will attempt to use. See section 5.2.3, "Handle Perforce jobs and
jobspec".
Refreshing jobs updates all jobs in Perforce by replicating them from the defect tracker's database. This procedure is necessary if:
To refresh the Perforce jobs, follow these steps from the operating system command line:
python refresh.py. python run.py. To uninstall the P4DTI, follow these steps:
/etc/rc.d, and so on. rpm -e p4dtiTo troubleshoot a problem with the P4DTI, follow these steps:
Look in the P4DTI log. If you find an error message, see if it is listed in section 11.2, "Error messages by identifier".
Check your configuration against section 5.1, "P4DTI configuration". Are the hostnames, userids, and passwords correct? Most problems with the P4DTI are caused by incorrect or inconsistent configuration.
See if there is any online support for your problem. Visit the P4DTI issue reports page <http://www.ravenbrook.com/project/p4dti/issue/>, choose your release and select the "Support information" report.
If you can't solve the problem, contact Perforce support (for details, see <http://www.perforce.com/perforce/support.html>). Provide the following information:
readme.txt that came with your P4DTI distribution to identify the release). p4 info" at the operating system command line. config.py file. This isn't a complete list, but it covers the errors that have been seen in testing, or which are reasonably likely to come up, or which need some explanation. If you see a message not covered in this section or section 11.3, "Other error messages" and which is not self-explanatory, please contact Perforce support (see section 11.1, "Troubleshooting").
The replicator has had an unexpected difficulty in accessing the Bugzilla database. Possibly there is a problem with MySQL or MySQLdb. Possibly you are running a version of Bugzilla which is incompatible with the P4DTI, or have customized Bugzilla in such a way that the P4DTI has become confused. Please contact Perforce support (see section 11.1, "Troubleshooting").
It looks as though you've been running with a later release of the P4DTI and then downgraded to an older release. We don't support downgrading; use the most recent release.
The P4DTI doesn't support your version of Bugzilla. Upgrade to a supported release (see section 3.3).
Preliminary checking of the parameters set in config.py has found a problem. Correct the named parameter and start the P4DTI again.
You are running a version of Bugzilla with different bug statuses
from those in the supported Bugzilla releases. The P4DTI has
attempted to choose a sensible translation of these bug statuses to
Perforce job states, but has failed. You may be able to fix this by
changing the closed_state parameter. Otherwise you must
modify your Bugzilla configuration.
The P4DTI chooses the names of states of Perforce jobs based on the status names in Bugzilla. It uses the following translation system:
closed_state parameter is not None, the P4DTI translates this status to "closed" and translates "CLOSED" to "bugzilla_closed".For instance, if the closed_state parameter is "RESOLVED", the P4DTI uses the following translation table
for the default Bugzilla statuses:
| Bugzilla status | Perforce state |
|---|---|
| UNCONFIRMED | unconfirmed |
| NEW | bugzilla_new |
| ASSIGNED | assigned |
| RESOLVED | closed |
| VERIFIED | verified |
| CLOSED | bugzilla_closed |
| REOPENED | reopened |
Alternatively, if the closed_state parameter is "CLOSED" or None, the
P4DTI uses the
following translation table for the default Bugzilla statuses:
| Bugzilla status | Perforce state |
|---|---|
| UNCONFIRMED | unconfirmed |
| NEW | bugzilla_new |
| ASSIGNED | assigned |
| RESOLVED | resolved |
| VERIFIED | verified |
| CLOSED | closed |
| REOPENED | reopened |
Check the closed_state parameter. It must be a valid Bugzilla state.
The P4DTI is incompatible with the version of Bugzilla which you are running. You are running a very old version of Bugzilla, or have customized Bugzilla.
Check the bugzilla_directory parameter. It must either be None or a string naming the Bugzilla installation directory.
If you're running Bugzilla under Windows, check that you've followed the instructions in section 3.6, "Win32 Installation Notes" of the Bugzilla Guide [Bugzilla 2001-08-07].
The P4DTI is incompatible with the version of Bugzilla which you are running. You are running a very old version of Bugzilla, or have customized Bugzilla.
Some fields are always replicated. For details, see the replicated_fields parameter.
Remove the system fields from your list of replicated fields and start the P4DTI again.
Each replicated field must only appear once in the replicated_fields parameter. Remove the duplicate and start the P4DTI again.
The P4DTI doesn't support all Bugzilla field types. One of the fields in your replicated_fields parameter has an unsupported type.
Remove the field from your replicated_fields and start the replicator again.
If you really need to have the field replicated, you have the following options:
replicator.translator to handle the field type (for the existing translators, see dt_bugzilla.py). For instructions on how to extend the P4DTI, and how to contribute your extensions back to the community, see the Perforce Defect Tracking Integration Integrator's Guide. You are running a version of Bugzilla with different bug fields
from those in the supported Bugzilla versions, and are trying to
replicate a field called "code". Perforce doesn't allow a job field
called "code". Remove the "code" field from the replicated_fields parameter or modify your
Bugzilla configuration to rename the field.
Reduce the number of fields that you replicate by removing items from the replicated_fields parameter.
Remove the named field from the omitted_fields parameter.
Remove the duplicated field from the omitted_fields parameter.
Remove the named field from the field_names parameter.
Remove the duplicated field from the field_names parameter.
The field_names parameter, combined with default field naming, gives the same Perforce field name to more than one Bugzilla field. Change that parameter so that each replicated Bugzilla field gets a unique Perforce field name.
A Perforce user has made a change to a bug which Bugzilla would not allow them to edit.
Bugzilla bugs can be grouped into "bug groups", which restrict the ability of users to view or edit them. Perforce protections cannot express these bug groups, so the replicator must enforce the Bugzilla restrictions by rejecting changes made by users outside the necessary bug group.
Another possible cause is that the P4DTI has failed to find a Bugzilla user corresponding to the Perforce user. See section 3.4, "User accounts" for details of how users are mapped from one system to the other, and how to diagnose problems.
A Perforce user has made a change which Bugzilla would not have permitted them to make.
Bugzilla has complex access controls which prohibit some users from making some changes to bugs. Perforce protections cannot express these controls so the replicator enforces these controls by rejecting changes to jobs which would not be permitted by Bugzilla.
Another possible cause is that the P4DTI has failed to find a Bugzilla user corresponding to the Perforce user. See section 3.4, "User accounts" for details of how users are mapped from one system to the other, and how to diagnose problems.
A Perforce user has changed a job's status to "duplicate".
When a bug is marked as a duplicate in Bugzilla, the number of the other bug is provided and a message identifying it is appended to the long description. The Perforce job interface provides no easy way of expressing this, so the replicator does not allow it.
A Perforce user has changed the 'status' field of a bug in a way not permitted by Bugzilla. For instance, moving a bug directly from UNCONFIRMED to CLOSED. These transitions are not allowed in Bugzilla, and the replicator enforces that prohibition by rejecting such a change.
It is difficult but possible to cause this error by making more than one change to the status in rapid succession (between two consecutive replicator polls). The replicator can't tell if that has happened, so has to reject the change anyway.
A Perforce user has made a change to a field which the replicator treats as read-only. See section 5.1.5, "Choosing which fields to replicate".
A Perforce user has changed the long description text in some way other than appending to it. See section 5.1.5, "Choosing which fields to replicate".
These errors indicate a serious configuration error; someone's changed configure_bugzilla.py and broken it.
The P4DTI is incompatible with the version of Bugzilla which you are running. You are running a very old version of Bugzilla, or have customized Bugzilla.
A Perforce user has set a field, which corresponds to a numeric field in Bugzilla, to something which couldn't be converted to a number.
The replicator Perforce user (p4_user parameter) has an e-mail address that does not match the replicator_address parameter. See section 5.2.1, "Creating a Perforce user for the replicator".
There is no Bugzilla user whose e-mail address matches the replicator_address parameter. See section 5.3.2, "Creating a Bugzilla user for the replicator".
You have changed a user field in a job to a Perforce user who does not have a Bugzilla user record. The replicator is unable to replicate that field back to Bugzilla.