The P4CQ Integration

The P4CQ integration is an integration between the Perforce SCM tool, the Rational defect tracking tool ClearQuest, and the Release Engineering tool ReleasePro™.  In addition, it includes the optional add-on component (open-source) Perforce P4DB web browser originally contributed by Fredric Fredricson.  P4CQ is a nicely integrated solution.

An overview of P4CQ can be seen via the P4CQ presentation.  It explains the integration and benefits through ReleasePro, ClearQuest, and P4DB (web) screen shots.

The download consists of a zip file that contains the ClearQuest schema, all hooks, all daemons/replicators, and a modified P4DB (based on version 2.01).  The download does not contain the three applications themselves but does include P4DB.  Please note that P4DB is a completely optional add-on that is not required - it provides a CGI based, web based, drill up/down capability.

There is also a CCCQ integration available for a ClearCase/ClearQuest/ReleasePro environment.

P4CQ is lightweight, flexible and configurable.  The actual amount of code that makes up the integration is not extensive.  Different parts of the integration can be independently disabled, enabled, or modified.  It does not dictate a specific defect state transition diagram.  Here are diagrams of the defect and call-id state transition diagrams.  It is written almost entirely in Perl using the ClearQuest Perl API.  It works on both Windows and UNIX, and is distributed under the G.P.L. (GNU Public License).

P4CQ is currently available as open source software.  Consequently, maintenance and support is not normally offered except under a consulting contract.  (Creative arrangements are possible.)

P4CQ Primary Usage and/or Design Requirements

1. Provide a Unified Release Definition across the development tool chain:
   ReleasePro provides the integration of a release being a first class object within both Perforce and ClearQuest as well as the end user's run-time environment.  See the ReleasePro documentation for more details.
2. Support web (point and click) drill-down and drill up
   Support the drill-down or drill-up between releases, defects, changes and files.  That is, for any of the above objects, to be able to point and click to any other associated object.
3. Support the following queries:
   • What has changed in this release?  Specifically, in terms of changes, defects, or files.
   • What is contained in this release?  Specifically, in terms of changes, defects, or files.
   • What releases contain this defect, this change?
4. Not add a mission-critical cross Perforce/ClearQuest requirement
   Do not create a system where Perforce now requires ClearQuest to be up and running and vice versa.  Since a lot of activity is happening on the user's client machine (like updating workspaces, etc.) or on arbitrary machines (one never knows what type of system a QA engineer will be using to enter data), allow each application to continue to be used if the other application is unavailable.  Without intervention by a admin, let the system heal itself after such a break as well as not be blocked by such a break.
5. Low developer and manager overhead
   Low learning curve, maximize point and click usage models.  Also low deployment costs (server side based solutions).
6. Not dictate a specific defect state transition model
   The actual defect state transition diagram in independent of P4CQ.  This also supports ease of modification of the state diagram.
7. Add, as best as possibility, other good stuff...
   Try to keep the design simple, maintainable, scalable, etc.

Design and Implementation Overview

1. ReleasePro provides a release as a first class object
   To be able to support queries against a release of a software product, a release needs to be a first class object somewhere in the system.  ReleasePro creates this first class object and ClearQuest is used to store this first class object.  Thus, when a product release is created via ReleasePro, ReleasePro records the release in ClearQuest.
2. The defect database is mirrored (mostly) only into Perforce
   Because ClearQuest is so feature rich and customizable, it was clear that trying to replicate CQ business logic via Perforce and glue was not going to work.  It was going to be difficult enough to obtain proper usage of CQ and Perforce in of themselves.  To wit, to be able to change Perforce job data and then have the integration talk to CQ, determine that the operation was illegal, then get this information back to the user quickly in a reasonable manner is problematic both in usage and implementation.  The problem is that backing out the user's input data after the fact could be confusing as well as mysterious to the user.

   Having said that, it was convenient to support the reverse flow of data from Perforce to ClearQuest under certain conditions, most notably when submitting changes with attached defects.  This was implemented and tested (somewhat), but due to available resources, is turned off by default in the current release.  It can easily be enabled.  If at all possible, free email support will be offered to anyone interested in using this feature.

   So, by default the CQ defect data is only mirrored into Perforce jobs, and modifying any defect/job attribute including fixed data directly in Perforce will have no lasting affect.  Such changes are backed out by the system typically in one minute intervals.  Additionally, the CQ data is only partially mirrored - only the most important defect fields are mirrored.  This includes those fields needed to meet the requirements.  However, this is easily configurable.

3. P4DB provides a web based drill-down/drill-up interface
   The web is an excellent medium for supporting drill-down and drill-up, and P4DB provide this piece.
4. Other general notes of interest:
   • There is a p4change stateless record type to hold Perforce fixes data in ClearQuest.
   • There is a P4CQ_Disable stateless record type to support disabling the P4CQ integration either globally or on a per user basis.
   • There is a P4CQ.pm Perl module that does most of the none ClearQuest hook based work.  This file/functionality is incorporated into ClearQuest via a Global Scripts package to handle a majority of the hook based integration.