Perforce Defect Tracking Integration Project Requirements

1. Introduction

This document defines the requirements of the Perforce Defect Tracking Integration Project. The purpose of the document is to record and maintain our current best idea of what the customers want (the "holy grail" of the project, see [RB 1999-05-20]), so that we can justify project decisions in terms of those requirements, review project decisions, and achieve quality by meeting those requirements.

This document does not record our opinion of what we actually intend to do at any particular time: that information is in the project plan [RB 2000-08-10]. It does not record our opinion of what is feasible or possible. What the customer wants is what the customer wants, and we strive to approach it even if we can never satisfy it [RB 1999-05-20, 4].

The requirements are, as far as we can make them, an objective measure of what the users want, and what would best contribute to the projects goals [RB 2000-05-24]. They aren't a to-do list for the project. Meeting some of them may not be feasible, but we should still use them to measure the quality of our solutions.

This document is updated as the requirements change.

The intended readership of this document is anyone interested in the project.

This document is not confidential.

The unanswered questions in [RB 2000-05-05, 14] do not appear in this document. Their answers will be incorporated when known.

2. Summary

There are a great many requirements in this document. This section summarises those which have been most important to the project. Note that this section is written and maintained with hindsight. It would not have been possible to say which requirements were most important when we first framed them.

Requirements 1 to 5 are the key critical high level requirements for the project.

1. Defect tracker state is consistent with the state of the product sources.
2. The defect tracking integration makes the jobs of the developers and managers easier (i.e. make it easier for them to produce a quality product etc.).
3. It is easy to discover why the product sources are the way they are, and why they have changed, in terms of the customer requirements.
4. The interface that allows Perforce to be integrated with defect tracking systems is public, documented, and maintained.
5. The integration provides the ability to ask questions involving both the defect tracking system and the SCM system.

The most influential functional requirement is that users must be able to carry out routine tasks using either the Perforce's interface [requirement 41]. That is, users must not have to switch interfaces to carry out routine development or defect resolution tasks. Meeting this requirement makes it much easier for developers to keep defect tracking data up to date, and so gives managers a more accurate view of the quality of the software their teams are developing: information vital for planning, amongst other things.

Perhaps the second most influential requirement is that the project must deliver a kit that makes it possible for anyone to integrate Perforce with the defect tracking system that they use [requirement 20]. This demands that the software be in an open source form (requirement 23), using readily available tools (requirement 24), is cheap to modify (requirement 25) and extend (requirement 26).

The requirements to integrate with TeamTrack (requirement 6) and Bugzilla (requirement 18) were quite important, but that choice was mostly made by analysing the prospective defect trackers against the projects goals [RB 2000-07-04].

Installation time (requirement 63) and likeability (requirement 75) have had a big influence on the project, causing quite a major change of design after the alpha programme.

3. Document conventions

We give the requirements unique IDs so that we can refer to them in our justifications. The IDs are simply sequential numbers, and we refer to requirements as simply "requirement N".

The requirements are never modified in such a way as to make references to requirements invalid. This is vitally important as many project activities are justified in terms of requirements. References to requirements are even written into the source code.

• When a requirement changes in definition (i.e. its measure changes) then the old requirement is marked as obsolete and pointed at a new requirement, created with the new definition. This means that references to the old requirement are still valid.
• If a requirement is split into more detailed sub-requirements, it is marked as obsolete and pointed at the new requirements.
• If a requirement is deleted (because we believe it no longer reflects customer need) then it is marked as obsolete but not removed from the table.

We record the sources of the requirements, so that they are justified in terms of what customers have actually said. This means that we can understand the importance of each requirement, and can cope with change.

The words "task", "integration" and "kit" have specific meanings in the context of this project, as defined in [RB 2000-05-05, 2.3].

The requirements are presented in a table whose columns are:

• the requirement identifier;
• the measure for the requirement;
• the critical, essential, optional, and nice levels of the requirement (see below);
• sources for the requirement.

For functional requirements, the measure is just a statement which is true or not. For attribute requirements it's typically a scale of some sort and a unit.

The terms "critical", "essential", "optional" and "nice" have fairly precise meanings (originally defined in [RB 2000-05-05, 2.2]):

critical

The project would fail if the requirement were not met at this level. Failing to meet any critical requirement will cause the project to fail to meet its goals.

essential

The project should meet the requirement at this level, but the project could still meet its goals without meeting it, possible after renegotiation with the customer. Most requirements we document fall into this category.

optional

The project wouldn't fail to meet its goals if the requirement weren't met at this level. The project will try to meet this level, but may elect not to in order to deliver or because of constraints on resources.

nice

Meeting the requirement at this level would help it along, but in general this level should only be met if it can be done cheaply, for example, as a side-effect of meeting higher levels of other requirements. These requirements can contribute a great deal to customer satisfaction and goodwill. Also known as "extra credit".

The entry in each cell is a level for the measure; either a minimum level (for measures like likeability where higher levels are better) or a maximum level (for measures like cost where lower levels are better). The entries for an attribute requirement look like this:

Measure	Critical	Essential	Optional	Nice
Cost of the product, in dollars.	< 1,000	< 500	< 100	< 50

The above entries mean that it is critical that the cost of the product be less than $1,000, it is essential that the cost be less than $500, it is optional that the cost be less than $100 and it would be nice if the cost were less than $50.

The entries for a functional requirement look like this:

Measure	Critical	Essential	Optional	Nice
Product is blue.	Maybe	Yes	Yes	Yes

The above entries mean that it is essential that the product be blue (and therefore it is also optional and nice that it be blue) but it is not critical that it is blue (or that it is not blue).

The method used here is similar to the attribute specification method in [Gilb 1988, 9]. Our "critical" level roughly corresponds to Gilb's "worst limit", our "essential" level roughly corresponds to Gilb's "planned" and our "optional" and "nice" levels roughly correspond to Gilb's "best limit". Gilb's attribute specification tables also have a "now" column which we express in our project plan and quality reports.

4. Requirements

A. References

B. Document History

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.