Release Notes for the Perforce Defect Tracking Gateway Version 2009.1 Introduction These notes include release-specific information about the Perforce Defect Tracking Gateway. For details about installing, configuring and using this product, consult the Defect Tracking Gateway Guide, which is included in the distribution zip file. The file name for the user guide is p4dtg.pdf. The Perforce Defect Tracking Gateway integrates Perforce with third-party defect tracking systems. Perforce currently supports two systems directly (Quality Center and Bugzilla). Other defect tracking systems are supported by third-parties (e.g., Fogbugz from Fogcreek). This version of the Perforce Defect Tracking Gateway supports Windows XP, Windows Server 2003/2008, Windows Vista, Linux 2.6 and BSD 6. On Vista, you must use the "Run as Administrator" to launch the configuration tool, to enable it to install the replication service. The Perforce Defect Tracking Gateway requires 2006.2 or later Perforce server. The Mercury Quality Center 9.0 plug-in supports the Windows platform, using MSDE, SQL Server or Oracle as the underlying database. This plug-in supports Quality Center 9.0, 9.2 and 10.0. The Mercury Quality Center plug-in is not available for a Linux or BSD installation of the Perforce Defect Tracking Gateway. The Windows installation supports replication with both Windows and non-Windows installations of Quality Center. The Bugzilla 3.0 plug-in supports Windows, Linux and FreeBSD platforms using MySQL 5+. This plug-in supports Bugzilla 3.0.8 and 3.2.3. For more details, see the README file in the doc/bugz3mysql5 directory. -------------------------------------------------------------------------------- Installing the Perforce Defect Tracking Gateway WINDOWS INSTALLATION: To install the Perforce Defect Tracking Gateway, download and run the installer from the Perforce web site. Important note, if installing on a machine which has the 2006.2 version of P4DTG, before installing this version, first copy or move the config directory to a new location and then delete the entire 2006.2 p4dtg directory. LINUX/BSD INSTALLATION: To install the Perforce Defect Tracking Gateway, download the tar file and uncompress it in the directory where you intend to install the product. To test the basic operation of the system, invoke the p4dtg-test.exe executable and issue the following commands (issue the commands indicated by the prompt ">"; output consists of "Loading module" and "Module loaded" messages). WINDOWS: C:> p4dtg-test.exe > LL plugins\p4jobdt.dll Loading module: [plugins\p4jobdt.dll] Module loaded: plugins\p4jobdt.dll > LT Module tests passed > LF Module freed > LL plugins\qc90dtg Loading module: [plugins\qc90dtg] Module loaded: plugins\qc90dtg > LT Module tests passed > LF Module freed > Q LINUX/BSD: host% ./p4dtg-test > LL ./plugins/p4jobdt.so Loading module: [./plugins/p4jobdt.so] Module loaded: ./plugins/p4jobdt.so > LT Module tests passed > LF Module freed > Q Usage Notes - It is *important* to note that when creating a mapping with the Bugzilla plugin, that you may only map the Perforce field named "Fix Details" to the "Fixes" field. While the config tool will allow you to do otherwise, it is a runtime error to do so. - The most common cause of replication failure is updates that are made using the same username that the replication engine uses to update Perforce jobs. The engine does not replicate transactions that were submitted using its own username. To avoid this problem, ensure that this username is employed only by the replication engine. - The configuration tool requires write-access to the 'config', 'help' and 'repl' subdirectories. - Windows support for P4TICKETS: The configuration tool uses the ticket for the current user, while the replication service uses the ticket for the LocalService. Services in Windows run with a different environment than applications. To use tickets, leave the password field blank for the Perforce Data Source. You must obtain a valid ticket prior to running the configuration tool. After setting the ticket(s), copy the p4tickets.txt file into the C:\Documents and Settings\LocalService directory, so the replication server service can find the ticket file. - Linux/FreeBSD support for P4TICKETS: The configuration tool uses the ticket for the current user. When running as a daemon process, make sure that the owner for the process has a valid ticket. To use tickets, leave the password field blank for the Perforce Data Source. You must obtain a valid ticket prior to running the configuration tool. - To replicate defect tracker fields that contain unmatched double quotes, ensure that the the target jobspec field is TEXT. - Connecting a plug-in of one type (such as Mercury) to a server of a different type (such as Perforce) can yield unexpected and unpredictable results, including hanging of the configuration tool. If this happens, kill the application and specify a server of the correct type for the selected plug-in. - The replication engine runs as a process that is spawned by a Windows service. The configuration tool automatically installs the service when you start replication for the first time. The service is deleted when you delete the associated mapping. After installation, use the configuration tool to start and stop replication for specific mappings. To ensure that the replication engine restarts when the machine is rebooted, use the system Service control panel to set the replication service to Automatic. If you configure the replication engine as an Automatic service, you must run the replication engine on a machine other than the machine where Perforce and Quality Center are running, because you cannot control the order in which Windows starts services. - On Linux and FreeBSD, use the configuration tool to start and stop replication for specific mappings. From the shell, you can start and stop the replication engine using the following commands (where P4DTGDIR is the location where P4DTG is installed and MAPNAME is the name of the specific mapping). Start replication: cd P4DTGDIR ./p4dtg-repl MAPNAME & Stop replication: (The replication engine will exit safely.) cd P4DTGDIR touch repl/stop-MAPNAME The engine will delete the repl/run-MAPNAME file when it exits. - Configuration files created by the 2006.2 Beta release of this product are not compatible with configuration files used in the production release. If you participated in the Beta, you must run the configuration tool to rebuild all of your configuration files. Configuration files created by the 2006.2 release of this product are compatible with this release. - If Quality Center is configured to support a strict workflow, do not mirror any fields used to enforce that workflow. Because the Perforce jobs subsystem does not provide support for workflow rules, updates to Mercury Quality Center fields that are used in workflow enforcement might violate those rules, causing the transaction to be rejected. - If a change on the Perforce side is rejected by Mercury Quality Center, the Perforce job is marked as being in an error state, and further attempts to replicate it cease until the error is corrected. Error states are recorded in the DTG_ERROR field of the affected job. - Quality Center reports errors using a "Dispatch Error" format. For more detailed information about these error conditions, check the log file that is generated by the replication engine. -------------------------------------------------------------------------------- Major new functionality in 2009.1 #192863 (Bug #24625) Log level and other replication attributes can be configured using the "Edit attributes..." button on the Map Editor in the Configuration tool. Log Levels: 0: Only log errors 1: Log errors and warnings (default) 2: Log errors, warnings, and some information messages 3: Log everything in great detail (Generates a very large log file. Use only for limited times.) Polling Period: specifies how long the replication engine sleeps before beginning a new replication cycle. The default is 5 seconds. Connection Reset: specifies how often the server connections are automatically reset during replication. Do not change unless directed to by Perforce Support. In general, this setting minimizes any plug-in-specific memory leakage. For example, the COM interface for the Quality Center plug-in has some memory issues which requires this setting. The default is 1000. #191281 (Bug #30938) Added special fields for the current server, user and project. These are treated as read-only SELECT fields and are intended for use in segmentation. The names for these fields begin with "DTGConfig-". If the plug-in supports attributes, they are displayed as read-only SELECT fields with a prefix of "DTGAttribute-". #195378 (Bug #32818) The Bugzilla plug-in provides a special field called "Status/Resolution", which can be mirrored in Perforce with an appropriate SELECT field. Changes to this field are replicated to both the "Status" and "Resolution" fields in Bugzilla. See the Bugzilla README.txt for more information. #202595 (Bug #34196) The Bugzilla plug-in provides a special read-only field called "Product/Component", which can be copied to Perforce as needed to support segmentation of bugs based on specific components. See the Bugzilla README.txt for more information. Minor new functionality in 2009.1 #195353 (Bug #33241) The Bugzilla plug-in has changed the format for the Description (a.k.a. Comments) field. The "-- Comment N: ..." information is now listed at the end of the text for the comment, instead of being the first line. Jobs are updated when individual replication occurs. To force all jobs to be updated, choose "Sync from start". #194797 (Bug #32671) The configuration tool now allows editing of the plug-in type when the predefined plug-in is not found. This usually only happens if the plug-in changed its name from one version to the next. More detailed status information is displayed for this case and when the server/port or user information is missing. #193801,193977 (Bug #33047,33117) The replication engine logs and exits after an attempt to copy or mirror special DTS fields that are intended as append-only targets for Fix Details. Currently, only the Bugzilla plug-in provides such a field ("Fixes"). The configuration tool enforces this restriction. #191784 (Bug #31327,32944) The Bugzilla plug-in's server trigger now has an option to prepend a text string to the name of a new job. #198078 (Bug #33538) The replication engine log warnings if DTG_ERROR is set to 1, 2 or 3 (increasing detail). #203166 (Bug#34299) In Quality Center, "IDispatch error #10208" typically indicates that the issue is locked due to someone editing it. This will fail out the associated job. Typically, you only need to remove the DTG_ERROR field in the associated job to restore replication for this defect. Bugs fixed in 2009.1 #209552 (Bug #34847) Do not crash if a field in a DTS->SCM mapping does not exist. #209552 (Bug #34848) If either server are unreachable or their plug-ins are missing, do not perform field level validation within the replication engine. #204585 (Bug #34429) Check the ModUser and ModDate fields for existance and valid type before beginning replication. If they are either missing or the incorrect type, log the invalid configuration and exit. #204164 (Bug #34189) The replication engine correctly replicates the "Job:" value to the defect tracking issue (and vis versa) for newly created Jobs. #203331 (Bug #34321) The replication engine no longer leaks a small amount of memory when certain error conditions occured. #203108 (Bug #34300) The DTG_ERROR field will be correctly written when the replication engine fails to save either a job or a defect. #201118,201332 (Bug #27000,32582) Quality Center plug-in ignores the BG_DETECTED_IN_REL, BG_TARGET_REL BG_TARGET_RCYC, and BG_DETECTED_IN_RCYC fields preventing a "Type mismatch" error in the COM library. #199663 (Bug #33757) The Bugzilla plug-in on FreeBSD would fail for certain data, citing the unresolved symbol "floor()". This has been fixed. #197934 (Bug #33505) The p4dtg-test tool no longer crashes when only a space is entered as input. #196971 (Bug #30165) When attributes are changed, the configuration tool now prompts the user to recheck the connection. #196712 (Bug #33393) p4dtg-test tool now accepts either "quit" or "exit" to terminate the application. #196495 (Bug #33369) p4dtg-test tool requires commands to be the only text instead of just looking for the prefix. For example, "exit" is no longer processed as the "e" (echo) command. #194731 (Bug #33164) On Windows, the configuration tool now displays version information when invoked with the -V option. -------------------------------------------------------------------------------- Major Changes in Release 2008.2: #160128 Support installations of Perforce and Defect Tracking plug-ins that contain unicode character support. (Bug #22645) #151469 Support integration with Bugzilla. (Bug #23074) #161580 Replication can be configured to wait instead of exiting when a server is offline. (Bug #27320). Changes since Release 2008.2: #199977, 199986, 200010 Multiple fix-updates were only having a single one logged in the Bugzilla comments field after the fix for Bug #33048. (Bug #33869) #195695 The Bugzilla plug-in was updating the timestamp of a bug twice whenever the Fixes field was part of a set of updates. This resulted in an UPDATE failure. The plug-in will now only update the timestamp once per set of changes. #195451 Replication engine will double check for server connectivity when a plug-in does not implement the server_offline interface. This will allow replication to wait when the Perforce server is offline but the DTS server is online. (Bug #33264) #193049, 194225 In the Bugzilla plugin, mapping a field other than the Perforce "Fix details" to "Fixes" could cause looping replication. A mapping of this sort is now a runtime error. (Bug #33048) #189241 The Bugzilla plug-in was not updating the Bugzilla bug's modification time when the only update was a new fix from Perforce. This would delay replication of that data until another change was made to the bug. (Bug #32616) #189293 Bugzilla plug-in could not be found after upgrading from the P4DTG Beta. This has been addressed by documenting a simple workaround in the Release Notes. (Bug #32604) #187618, 187669 The Bugzilla plug-in did not properly escape data, which could result in invalid SQL statements. (Bug #32516) #187359, 187401 The Bugzilla plug-in's trigger now treats "" as an unset value in job fields. These fields are set to "" when a job is created using P4Win. (Bug #32489) #187263 The Bugzilla plug-in's trigger will now give the correct error message when denying the creation of a new job. (Bug #32477) #187255 The Bugzilla plug-in's trigger no longer considers trailing whitespace in the DTG_* fields in support of client programs that automatically trim it. (Bug #32475) #186659 Accept "" as an unset value for the DTG_DTISSUE and DTG_MAPID fields. These fields are set to "" when a job is created using P4Win. (Bug #32383) #184234 Correctly deallocate memory in the Bugzilla plug-in to prevent issues on strict memory usage platforms like Vista. (Bug #32155) Changes since Beta Release 2008.2: #175737 Erroneous "Unable to stop service" message in replication log has been removed. (Bug #31222) #171701 Correctly calculate DataSource in-use reference counts when mappings are deleted. (Bug #31440) #171667 Restrict the number of options required for mapping SELECT fields that are the basis of segmentation. This change allows for the mirroring of SELECT fields that have different numbers of options but are equivalent as a result of the segmentation restrictions. (Bug #31168) Changes in Beta Release 2008.2: #165390 For new DTS DataSources, checking connection maintains current project setting if possible. (Bug #30730) #165235 New segments always start with empty assigned lists. (Bug #30661) #165229 Segment editor allows the SELECT field to be changed when no segments map any of the options for that field. (Bug #30638) #165149 Configuration tool now properly handles the editing of a segment that had one of its options removed from the underlying SELECT field. (Bug #30714) #165064 DataSource and Map names must be unique regardless of case. (Bug #30645) #165063 The set-MAPNAME.xml file is deleted when the map-MAPNAME.xml file is deleted using the configuration tool. (Bug #30715) #165002 The replication engine no longer crashes when exiting. (Bug #30602) #164960 p4dtg-test no longer crashes when a value is omitted for the AS (Attribute Set) command. (Bug #30678) #164925 Enabled deleting of brand-new data sources that have never been saved. (Bug #30664) #164912 Display the nickname for the server in the segment editor when the server source is new. (Bug #30656) #164904 Corrected typo in error message requiring a valid connection to the server before allowing segmentation. (Bug #30568) #163715 Fix details for FileList can now be added independently from the FixDescription. (Bug #30447) Changes since release 2008.1: #160411 Correct the set of required fields to only those fields which are used by the system. (Bug #30184) #158674 Keyboard navigation of field lists in the Mapping Editor of the configuration tool will update the mapping buttons accordingly. (Bug #29988) Changes in Release 2008.1: #150549 Filter Replication - Enables any DataSource to be segmented using a specific SELECT field so that a single DataSource can be used in multiple replication mappings. (Bug #24777) #148395 DataSource specific Attributes - Support plug-ins that require additional information for configuring a DataSource. (Bug #24780) #158128 The configuration tool will report failures to write or delete configuration files to/from the 'config' directory. (Bug #29950) #153291 The Mercury Quality Center plug-in supports user configuration of the time offset using the Attribute editor. The default value of 30 seconds should be acceptable for almost all instances. (Bug #29165) #158206 The configuration tool checks for write-access to the config, help, and repl subdirectories on start-up. (Bug #29959) #155501 The Select Mapping Editor in the configuration tool will treat duplicate options for a SELECT field as a single entity. (Bug #29606) #155355 Correctly report malconfigured DataSources. All Perforce sources require a 'Job:' field, a field containing the last modified by, and a field containing the last modified date. All DTS sources require a field containing the issue/defect id and a field containing the last modified date. (Bug #29570) Replication engine will check for required fields and exit with an appropriate message if missing. (Bug #29556) #154937 The About help page now has navigation links at the bottom of the page. (Bug #29390) #154443 If the machine running the replication runs out of disk space, there is a chance the setting file may become corrupted or out-of-date. The configuration tool will report such errors and you can resolve them by restoring the backup copy of the setting file in the config directory. The backup ends in '.old'. Alternatively, you can simply delete the set-MAPNAME.xml file and reset the start date using the configuration tool. (Bug #29295) #154362 Prevent duplicate DataSource and DataMapping names (Bug #29300) #157077 The replication log now displays the proper path for files. The use of '/' and '\' for directory separators has been normalized. (Bug #29172) #149920 The replication engine now reports which server has failed to return the current date. (Bug #28590) #149920 The replication engine reports more information on which server is failing on a connect request. (Bug #28591) #151536 The configuration tool now checks for the correct directory structure upon startup and report any errors. (Bug #28907) Changes since Release 2007.1 May 3, 2007: #148124 Support for P4TICKETS. To use tickets, leave the password field blank for the Perforce Data Source. A valid ticket must be obtained prior to running the configuration tool - if the ticket expires, replication stops. After setting the ticket(s), copy the p4tickets.txt file into the 'C:\Documents and Settings\LocalService' directory so that the replication server service can find the ticket file. (Bug #28464) Changes since Release 2006.2 January 15, 2007: #122074 DTS Source Creation requires a Project to be selected before enabling the "OK" button to save the new source. (Bug #24481) #122074 p4dtg-test rejects calls to Perforce-only extensions for non-perforce plug-ins. (Bug #24647) #122074 p4dtg-test help text now states that the SD method might require a connection to a specific project to work correctly. Quality Center plug-in has this requirement. (Bug #24648) #122074 p4dtg-test help text now states that the DE method requires the date to be formatted according to the plug-in being tested. (Bug #24649) #122074 Perforce plug-in now puts single-line field values on the same line as the field name. (Bug #24652) #119397 Configuration tool no longer crashes when connecting to a non-p4d server using the p4jobs plug-in. (Bug #24256) #119387 Prevent replication engine from being run when the Defect Tracking Source is not providing a "Last Modified Date" field. (Bug #24242) #119387 Correct non-enabling of possible select values when all select value mappings are deleted using UNMAP ALL. (Bug #24226) #118987 Prevent running the replication engine on an empty mapping description. (Bug #24206) #118866 Correct check for incomplete select mappings to not consider deleted mappings. (Bug #24198) #118864 Prevent changing of nicknames after they have been established. (Bug #24200) #118864 Prevent deletion of Data Sources that are used in mappings. (Bug #24194) #118755 Prevent invoking replication on a mappings marked for deletion (Bug #24190) #118383 To ensure that all new Mercury issues are properly replicated, the Quality Center plug-in subtracts 30 seconds from the timestamp used used to detect new or changed issues. (Bug #24153) #117382 Enable the Perforce server and the Defect Tracking server to run in different time zones. (Bug #23792) #117101 Enable the configuration tool to display long project names. (Bug #23954) #117035 P4DTG now supports the following Mercury date formats: DMY - Day Month Year - dd/mm/yyyy MDY - Month Day Year - mm/dd/yyyy YMD - Year Month Day - yyyy/mm/dd 24 hr - hh:mm:ss 12 hr - hh:mm:ss AM|PM Other formats are not supported. (Bug #23916) #116366 The replication engine no longer crashes if the Defect Tracking System returns a NULL value for a defect's LastModifiedDate field. (Bug #23855) #115643 Support running the replication engine using Windows services. (Bug #23050)