Ravenbrook / Projects / Perforce Defect Tracking Integration / Project Documents
Perforce Defect Tracking Integration Project
This document describes proposals for the technical architecture of a system to integrate Perforce's software configuration management system with defect tracking systems. It briefly discusses the extent to which the architectures support the customer requirements described in [RB 2000-04-11] and the technical requirements described in [RB 2000-05-05b].
The purposes of this document are:
The intended readership is Perforce senior technical staff and anyone working on architecture evaluation and on the design of the defect tracking integration. It could be open to all Perforce staff.
This document is not confidential.
We propose the following architectures:
The tracker-client architecture meets only the tracker to Perforce requirements [RB 2000-05-05b, 6.1] but could be combined with one of the other architectures to make a full integration. On its own, this architecture needs no changes to the Perforce clients or the Perforce server.
The replication architecture looks as through though it could meet all the functional requirements. Because information is replicated there needs to be a way of dealing with inconsistency. This may result in increased administration cost and worse handling and we need to investigate whether this architecture will meet the requirements for these attributes [RB 2000-05-05b, 14.10].
The union architecture is elegant and is the most flexible and open-ended in terms of the variety of queries it supports. However, it may need new and untried technology and it is therefore risky.
The single-database architecture needs fewer external components. It needs complex changes to Perforce. It could be costly.
The messaging architecture meets workflow requirements but fails to meet the requirement to be able to carry out queries about Perforce data from either the defect tracker's interface or from Perforce's interface [RB 2000-05-05b, 6.2].
The manual architecture would be very cheap to develop [RB 2000-05-05b, 13.3].
Currently, the replication architecture looks best but more detailed investigation and evaluation of the proposals is needed to be sure of this impression. There may also be other architectures that would meet the requirements. Evaluation of the proposals and investigation of alternative should continue in parallel with further requirements gathering and test development, as described in the project plan [RB 2000-02-02, 9.2].
The defect tracking client is also a Perforce client. The defect tracking client connects to the Perforce server using the Perforce API. It provides an interface through which the user can carry out routine software configuration management tasks from the defect tracker's interface. See figure 1.
Figure 1. The Tracker-client architecture
The defect tracking client could use the API to examine and change Perforce jobs, monitor changes to jobs and thus provide some of the features of the replication architecture [3.2].
The tracker-client architecture may be used as a component of each of the architectures described below, to provide the tracker-to-Perforce integration.
The tracker-client architecture fails to meet the requirement that users must be able to carry out routine defect resolution tasks from the Perforce interface [RB 2000-05-05b, 6.2]. There is no way for changes made through the Perforce interface to affect the defect tracker's database. This fails to meet the consistency requirement [RB 2000-05-05b, 3.1].
With the variation, the defect tracking client is rather like the replication daemon [3.2.1] but in order to maintain consistency a defect tracking client must be running all the time. But there may be many defect tracking clients and they are in the wrong place (on the client machines).
Data needed to meet the integration requirements is stored in both the defect tracker's database and Perforce's database. In practice, this is likely to be:
A daemon establishes and maintains consistency between the two databases, copying data back and forth as needed. See figure 2.
Figure 2. The replication architecture
Queries from the defect tracker's interface can be resolved using only the defect tracker's database. Queries from Perforce's interface can be resolved using only Perforce's database.
There is some choice as to what entities in the defect tracker are replicated into Perforce jobs. Most defect trackers have a single entity (the issue) in which case the replication is simple. But some defect trackers may allow hierarchical decomposition of issues, or allow separate representation of issues (a discrepancy between the user requirements and the product), "changes" (programmes of work to address an issue in a release) and tasks (a single item of work) [RB 1998-02-17]. In this case it is probably the task that should be represented by the Perforce job, since each change is made as part of a task.
There are three ways in which the replication daemon might work:
A new relation between jobs and filespecs is needed to support the requirement to be able to associate documents with tasks [RB 2000-05-05b, 7.1].
There is a user requirement to be able to represent the effect of a changelist on a job [RB 2000-05-05b, 6.3.1]. This could be done by extending the fixes relation in Perforce.
The Perforce clients must be extended to provide interfaces to this additional information.
The replication daemon may be used to double-check consistency as well as to maintain it [RB 2000-05-05b, 10.1]. It may also be used to initially establish the replication when the integration is started for the first time.
In the variations without distributed transactions, there will be a short period after each change when the defect tracker's database is inconsistent with Perforce's database and queries on the two sides give inconsistent answers.
This period is shorter, and the load on the servers is lower, in the variation daemon is notified whenever a change happens [RB 2000-05-05b, 14.8].
Note that defect tracking vendors generally provide interfaces through which other applications can access and update information in their database, but generally don't provide a mechanism for notifying other applications when a change happens [RB 2000-05-05b, 4.1]. (The defect tracker may use an RDBMS that provides support for triggers to be run when data changes; this feature may be used to notify the replication daemon.)
In the variations without distributed transactions, the databases may become inconsistent in ways that the replication daemon is unable to resolve. For example, one user associates a file to a task while simultaneously another user disassociates the same file from the task. Or a developer submits a change on a task while simultaneously a manager assigns the task to someone else so that the developer no longer has permission to submit changes on that task.
There are various strategies for resolution of these inconsistencies:
All strategies but the first two impose an administration cost on the organization [RB 2000-05-05b, 14.9, 14.10].
The variation with distributed transactions may be complete overkill for this application, and will be costly and risky. See also the union architecture proposal [3.3], which is a similar idea.
A database unification layer provides a view of the two databases (the defect tracker's database and Perforce's database) as a single database. This allows queries combining information from the two databases (for example, joins between the issue and fixes relations) to be carried out [RB 2000-05-05b, 11.4].
Each relation is stored only once, either in the defect tracking system's database, or in Perforce's database. For example, the issue relation may be stored in the defect tracker's database, while the fixes relation may be stored in Perforce's database.
The database unification may be put into the system at two points:
Figure 3. The union architecture
Figure 4. The variation of the union architecture
The union architecture allows many more sorts of queries than the other architectures support [RB 2000-05-05b, 11.4]. It is very open ended. It is also a natural way of implementing distributed transactions which would allow the integration to enforce consistency [RB 2000-05-05b, 3.1].
There is no delay for synchronization [RB 2000-05-05b, 14.8]. There is no possibility of data becoming inconsistent between Perforce and the defect tracking system [RB 2000-05-05b, 14.10].
The variation in which the unification architecture is implemented as a proxy may be a way to provide queries combining information from the defect tracker's database and Perforce's database without changing the Perforce server. This could reduce the load on Perforce technical staff [RB 2000-05-05b, 13.2.1].
The Perforce clients must be extended to provide interfaces to the information in the defect tracker's database.
This is experimental and untried technology. It will therefore be costly and risky.
Data needed to meet the integration requirements is stored in the defect tracker's database only. The Perforce server is modified so that when it needs job-related information, it looks in the defect tracker's database instead of its own. See figure 5.
Figure 5. The single-database architecture
The single-database architecture has fewer external components than either the replication or union architectures, so it's more maintainable [RB 2000-05-05b, 14.5] and installable [RB 2000-05-05b, 11.2].
As in the union architecture, each relation is stored only once [3.3.1] with corresponding benefits [3.3.3].
The single-database architecture may need complex changes to be made to the Perforce server to provide a back-end interface flexible enough to query a wide variety of defect tracking databases. This could put a lot of load on Perforce technical staff [RB 2000-05-05b, 13.2.1].
A defect resolution task is represented as a workflow token which is passed back and forth between the defect tracker and Perforce. The token represents the responsibility to manage the task.
For example, when a developer is assigned a task (using the defect tracker) a message is sent to Perforce. Perforce creates a job that corresponds to the task. When the task is completed (using Perforce) Perforce sends a message back to the defect tracker, containing all relevant data.
This architecture was suggested by Mark Buckallew <mark.buckallew@remedy.com> of Remedy during a phone conversation [RB 2000-05-05a]. It is almost certainly of no use (for our purposes) on its own, but does give a different perspective.
When a task is in progress in Perforce, you can't ask questions about it from the defect tracking interface. After the task has been completed, you can't ask questions about it from Perforce. (Perforce must forget about the task or else the data could become inconsistent.)
The messaging architecture meets workflow requirements when using Perforce's interface [RB 2000-05-05b, 6.2], but these are orthogonal to Perforce Software's user's requirements for defect tracking integration.
The project develops no software. Users must maintain consistency between the defect tracker and Perforce by entering cross-reference data by hand. See figure 6.
Figure 6. The manual architecture
For example, a connection between issues and jobs may be maintained by creating by hand a new job whenever a new issue is created, and putting the job ID in the issue description and the issue ID in the job description or submission comment.
This corresponds to the way in which a number of Perforce customers work today.
The manual architecture meets all the functional requirements, which only goes to show how important the attribute requirements are. The project has to increase consistency, usability and so on in order to succeed. These are harder to specify and more important than functions [Gilb 1998].
This section is here to make you think.
We've presented six possible ways forward for the project, but this is only a starting point for making the decision of which architecture to use.
| [RB 1998-02-17] | "Change management handbook"; Richard Brooksby; Ravenbrook Limited; 1998-02-17. |
| [RB 2000-02-02] | "Steps to defect tracking integration"; Richard Brooksby; Ravenbrook Limited; 2000-02-02. |
| [RB 2000-04-11] | "User requirements for defect tracking integration"; Richard Brooksby; Ravenbrook Limited; 2000-04-11. |
| [RB 2000-05-05a] | "Phone meeting with Mark Buckallew of Remedy" (e-mail message); Richard Brooksby; Ravenbrook Limited; 2000-05-05 22:10:57 GMT. |
| [RB 2000-05-05b] | "Requirements for defect tracking integration" (e-mail message); Richard Brooksby; Ravenbrook Limited; 2000-05-05. |
| [Gilb 1998] | "Principles of software engineering management"; Tom Gilb; Addison-Wesley; 1998; ISBN 0-201-19246-2. |
| [GDR 2000-05-03] | "Requirements and use cases for Perforce/defect tracking integration"; Gareth Rees; Ravenbrook Limited; 2000-05-03. |
| [GDR 2000-05-11] | "Defect Tracking Project Meeting, 2000-05-11"; Gareth Rees; Ravenbrook Limited; 2000-05-11. |
| 2000-05-08 | GDR | Drafted based on written notes and discussions with RB. |
| 2000-05-09 | GDR | Edited based on discussion with RB. |
| 2000-05-10 | RB | Added references and some extra analysis to connect to requirements report [RB 2000-05-05b]. Added figures. |
| 2000-05-25 | RB | Converted to HTML in preparation for project publication. Marked as "not confidential" as agreed with Perforce [GDR 2000-05-11, 5]. |
| 2000-05-30 | GDR | Added element identifiers and links to sections and references. |
| 2000-06-30 | GDR | Made references link directly to target, rather than the references section. |
These figures should accompany this report as attachments:
Copyright © 2000 Ravenbrook Limited. This document is provided "as is", without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this document. You may make and distribute verbatim copies of this document provided that you do not charge a fee for this document or for its distribution.
$Id: //info.ravenbrook.com/project/p4dti/doc/2000-05-08/arch-proposals/index.html#11 $
Ravenbrook / Projects / Perforce Defect Tracking Integration / Project Documents