Plan of work for the P4DTI Integration Kit

1. Introduction

This document outlines things that need to be done in order to develop and deliver the Perforce/Defect Tracker integration kit, to meet requirements 20, 21 and 22.

The intended readership is P4DTI development staff.

This document is not confidential.

2. Questions about the kit

2.1. What should the product be called?

It will be the "Perforce Defect Tracking Integration Kit", or "P4DTI Kit" for short.

2.2. What should the deliverable consist of?

It's probably best for the deliverable to be a tarball of /project/p4dti/version/VERSION/.... Keeping things simple is good because it reduces the error rate. (The P4DTI release procedure is getting very heavy and error-prone.)

The deliverable will be called p4dti-kit-RELEASE.tar.gz.

2.3. How should releases of the integration kit be numbered?

When the P4DTI Kit is produced from the same sources as a release of the P4DTI proper, it should share the same release number. Otherwise, it gets the next release number in sequence, as for the P4DTI.

3. Code improvements

3.1. Messages

We've been planning to give identifiers to messages since early on (see job000030). If we don't do so now, then people writing extensions won't use them and it'll be hard for users of the extensions to understand what's going on.

Also, it would be very useful for people debugging the replicator (or their extension to it) to have access to verbosity control (see job000060 and job000065).

I suggest the following steps:

1. Make a class for messages (with message id and level of importance); see [RB 2000-12-16].

2. Use this class and suitable subclasses thereof when raising exceptions of logging messages.

3. Document the message class hierarchy and how to use it.

4. Provide a procedure for generating new message ids (how do we allow people to develop extensions independently without their messages conflicting?).

5. Turn the verbose flag into a verbosity level.

6. Add suitable levels of importance to existing messages.

7. Add more debugging messages to the replicator.

8. Update the AG to use the new message ids.

3.2. Module organization

Why does the replicator.py contain both the interface definitions (defect_tracker, defect_tracker_issue and so on) and the implementation of the replicator class? This has led to problems of import loops, where a module needs the interface definition but has to import the implementation as well.

3.3. Source code layout

Source code should be laid out like documents, with introduction, sections, references, document history. (The last is done already.)

See [RB 2001-03-09] for some suggestions on how this should look.

3.4. References to design

The code does not refer to its design. We should add proper references. See [RB 2001-03-09] for some suggestions on how to do this.

Implementations and design notes should refer to the Integrator's Guide where relevant.

3.5. Action field and conflict resolution

No-one has requested the ability to specify their own conflict resolution policies, or shown any hint of wanting such a feature. We found in alpha testing that the resolver would be an onerous role.

So why not remove all code to do with the P4DTI-action field and the resolver? We could remove the P4DTI-action field from the jobspec and simplify the replicator algorithm considerably (the conflict resolution bits are very long and hard to follow).

4. Documentation improvements

4.1. Architecture

The Architecture needs bringing up to date. It still mentions the tracker-client architecture, for example.

4.2. Replicator design

The replicator design should be brought up to date by integrating all e-mail design decisions. The following decisions need to be integrated:

1. [RB 2000-11-08]
2. [GDR 2000-11-17]
3. [RB 2000-11-20a]
4. [RB 2000-11-20b]
5. [RB 2000-11-20c]
6. [NB 2000-11-23]
7. [NB 2000-11-24]
8. [RB 2000-11-28a]
9. [RB 2000-11-28b]
10. [RB 2000-11-28c]
11. [RB 2000-11-29]
12. [RB 2000-12-16]

See also [RB 2001-03-09] for some suggestions from RB for improvements to the design document.

The design should refer to the architecture, and the architecture should be covered by the design documents (expand on the architecture to get to the design documents; for example by exploding the architecture diagram to show design elements).

The design should refer to requirements wherever appropriate.

4.3. Bugzilla database schema design

Bugzilla needs a schema document that contains all the elements listed in Section 4, "Defect tracker database schema extensions" of the Integrator's Guide.

4.4. Integrator's Guide

The following work needs doing for the Integrator's Guide:

1. Add defect_tracker_filespec class documentation to Section 6, "The defect tracker interface module".

2. Write section Section 6.5, "Logging and error handling". (Once we've done the work listed in section 3.1 above.)

3. Document the p4.py module somewhere; describe the Perforce interface configuration in Section 7.2, "Perforce interface configuration".

4. Document the replicator configuration in Section 7.3, "Replicator configuration".

5. Explain in more detail what a configure_dt.py module needs to do in Section 9, "Adapting the configuration module" (perhaps give some example code).

6. Explain how to make the fabled "advanced configuration" in Section 7.5, "Making your own configurations".

7. Describe how to adapt the manuals in Section 10, "Adapting the manuals".

8. Write Section 11, "Making your work available to the community". Use P4DTI Project Contributions Procedure as a basis or refer to it.

9. Provide some examples. The TeamTrack and Bugzilla integrations are probably the best source of examples, it's just a matter of making the relation between each bit of code and the relevant bit of the Integrator's Guide clear.

10. Make the Integrator's Guide refer to new design documents.

4.5. Bugzilla interface design

The bugzilla.py module may need some design documentation, perhaps along the lines of the TeamTrack interface documentation. Not very important, except insofar as it can be used to illustrate the Integrator's Guide by example.

5. Plan

Work on the P4DTI Integration Kit should start with the elements that integrators will need (documentation and improvements to the code that affect the interfaces to which integrators will be working), and work out from that point through to the design documents. Changes to code that integrators won't look at can be left if resources are scarce.

Based on this priniciple, I suggest the following order of work:

1. Essential work on the Integrator's Guide (items 1, 3, 4, 5 in section 4.4).

2. Replicator design (section 4.2).

3. Messages (section 3.1; item 2 in section 4.3).

4. Action field (section 3.5).

5. Module organization (section 3.2).

6. Remaining Integrator's Guide work (items 6 to 10 in section 4.4).

7. References from design to architecture and requirements (section 4.2).

8. References from code to design (section 3.4).

A. References

B. Document History

Copyright © 2001 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.