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.