README for Perforce Defect Tracking Gateway (P4DTG) Redmine Plug-in
This document is intended for new users and for users who want an overview of
the Redmine plug-in. For details about using P4DTG, see the Perforce Defect
Tracking Gateway User's Guide.
--------------------------------------------------------------------------------
Overview
This plug-in mirrors fields between Redmine issues and Perforce jobs. Although
issues can be created only in Redmine, users can edit certain fields in a
Perforce job and have their changes mirrored in Redmine.
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+
Redmine 0.8+
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.
--------------------------------------------------------------------------------
Configuring the Redmine plug-in
To configure the plug-in, launch the P4DTG configuration tool and perform
the following steps:
1. Click the "Defect Tracking Sources" tab.
2. Click "New".
3. From the "Type" dropdown list, choose Redmine/MySQL.
4. Specify the login account details for your MySQL server in the "Server
connection details" fields. The MySQL account must have SELECT, INSERT and
UPDATE privileges on the host where P4DTG is running, for the Redmine
database.
5. (Optional) To configure attributes, click "Edit attributes..." and specify
options as follows.
Redmine username: If your Redmine user name is different from your MySQL
user name, enter it here.
MySQL database name: Specify the name of the Redmine database in the MySQL
server.
Fixes custom field: Specify the virtual custom field where fix information
is stored.
Unicode server: Specify whether the Redmine database uses or supports
Unicode (y/n). The default character set for Redmine databases is UTF-8.
Change offset: for heavily loaded servers, configure a delay to ensure
that all issues are replicated.
If your Redmine installation is large and highly active,
Redmine might save issues using a ModifiedDate that is earlier than the
time that the issue is actually committed to the database. This
discrepancy can cause the P4DTG replication engine to skip those issues.
To minimize this possibility, set Change offset something around 30
seconds. When using this attribute, mirror mappings should be kept to a
minimum as the system will encounter significantly more situations where
both the Job and the defect detects as having simultaneous changes to
replicate - the value in Redmine will override the value in Perforce.
Wait time: Specify the number of seconds that the MySQL server waits before
retrying an operation that returned an error. To stop replication when an
error occurs, specify -1.
Check privileges: Specify whether the replication engine checks for
sufficient access rights to the MySQL user before connecting. If in doubt,
leave it at the default.
6. To verify your configuration, click "Check connection and retrieve fields".
If your entries are correct, the configuration tool displays "Valid
connection to server".
7. Finally, configure your Perforce Source and mappings as described in the
P4DTG User Guide.
The Redmine plug-in adds the following fields to the list of defect tracker
fields that is displayed in the Gateway Mappings dialog:
Description: contains the combination of the Issue subject and body.
To display this information in the corresponding Perforce job, map this
field to a TEXT field in the Perforce job specification.
Notes: the aggregate of the Redmine "Notes" field.
To display this information in the corresponding Perforce job, map this
field to a TEXT field in the Perforce job specification.
Fixes: to append fix information to the Redmine issue "Notes" field,
map this field to the Perforce "Fix Details" field. You can specify details
to be appended, such as the change number or user who made the fix.
A note on replicated field requirements:
Please ensure that any fields' requirements are equivalent in Redmine and in
the Perforce Server's job spec. Fields that are optional in one system and
required in the other can cause replication to fail.
A note on defect tracker segmentation:
If you intend to use segmentation, please ensure that the segmented field
is mapped for replication. If it is not, the replication of any new Redmine
Issues will fail.
--------------------------------------------------------------------------------
Modifying a Redmine instance or Perforce job spec
Whenever making changes to a Redmine instance that would impact the Issues
system, or a Perforce Server's job spec, please ensure that P4DTG is stopped
first. The plug-in's configuration may need to be updated before P4DTG can be
started again.
Examples:
- If a project is to be archived, the defect tracker source for that project
should be removed first.
- If a new Issue status, priority, etc is to be added to Redmine, the Perforce
Server's job spec will need to be updated to include the new option. The
P4DTG mappings will also need to be updated to link the new select values.