Task Tracking With Gnats

Dev's interactions with the rest of the company are handled in large part through a modified version of the www-Gnats system. Here's the entry page for Worlds' customized system. The term for an individual feature-request item or bug-report item in Gnats is PR. This is theoretically short for Problem Report, although it's a misnomer since the feature-request PRs aren't really problems. Think of a PR as a task. The way that other departments request that Dev perform tasks is by submitting PRs to Gnats.

Use of Gnats doesn't mean that people in other departments shouldn't call up Dev programmers on the phone, or send them direct emails; such communications are a necessary supplement to PRs. But any substantive work task must be represented by a PR in Gnats in addition to such side-channel communications, so that the task can be tracked and so that it's clear who's responsible for what, when.

The system consists of two parts: the Gnats program, and the process (the set of rules) about how everyone should use that program. When both work properly the system delivers well-defined accountability at every stage in the life cycle of a PR. That is, PRs can't fall through the cracks, because the system defines at each stage who's responsible to advance the PR to the next stage.

Dev maintains the Gnats program; change suggestions for it should be submitted as PRs (to the Gamma project for now), just like any other request that Dev do a task. The rest of this document describes the rules that make up the process.

PRs with dates

Here's how it works. People in Prod or QA comes up with a feature that they want by some date, or a bug that needs to be fixed. They submit a PR describing the item, with the "due date" field set to the desired delivery date. The new PR is automatically in the open state, and the person who submitted it is called the PR originator.

The open PR goes to the gnats administrator, and is broadcast by email to a defined list of "interested parties", depending on the category. The programmers all see new programming PRs, for instance. This allows workers to start on critical PRs without a delay while the administrator reassigns them. Workers may reassign PRs to themselves (i.e. make him/herself the Responsible Party for the PR in Gnats), or wait for the Gnats administrator to do so.

The responsible party changes the PR state to analyzed, also changing the due date from the desired value given by the originator, to a date the responsible party can promise delivery by. This date might be very different from the date requested by the originator. The originator made a request that the responsible party will try to, but is not obligated to, satisfy. In contrast, the date given in an analyzed PR is the responsible party's promise, sealing a contract between responsible party and originator.

When the responsible party finishes the feature, s/he changes the PR to the feedback state. Now it is the originator's turn to take action. S/he decides whether the PR is completed to her/his satisfaction and changes the PR to the closed state if it is, or back to the open state with a detailed explanation of the remaining problem if it isn't.

At each stage in the PR's life cycle someone must act within a certain time period: a newly open PR must be redirected by the Gnats administrator within a day; the responsible party must change it to analyzed within a day; the responsible party must then change it to feedback by the promised date; the originator must change it to closed or back to open within a day of receiving a version that contains the resolution. These are guidelines, the spirit of the system is that dated open and feedback PRs should be acted upon ASAP.

Sometimes, for small items, the responsible party will fix the problem immediately and move the PR directly from open to feedback, skipping the analyzed state completely.

PRs without dates

The rules are different for PRs that don't have a date, which should be most of them. Many PRs submitted by QA are this sort, things that ought to be fixed, and perhaps are even critical, but aren't required by any particular date. Such PRs needn't go through an analyzed state, they can sit in the open state indefinitely until they are resolved, at which time they go directly to feedback. The severity and priority fields of such PRs are used to determining their scheduling.

Although dateless open PRs can sit around indefinitely, they are still on the list of things the responsible party intends to do. There's an implicit promise from the responsible party to the originator that the responsible party will get around to the PR in some reasonable amount of time. Sometimes the administrator and the responsible party will decide that certain PRs are not going to be done anytime soon, and are optional (i.e. the product can ship without it), in which case the responsible party moves the PR to the suspended state.

A suspended PR is one that the responsible party agrees is worth doing, but is making no promises about. It may still be done; on the other hand, it may not. It's kept in the system and still appears on the responsible party's daily PR printout as a reminder. The suspended state isn't used to reject a feature request; rejected feature requests are put into feedback right away, with an explanation, so that disagreements can be resolved.

Naturally, the originator receives notice when a PR's state is changed, and can reopen a suspended PR if it's not optional. Usually when this happens the project managers will need to get involved to decide whether the PR in question is optional.

Implications For Accountability

Originators should submit dated PRs at least a month ahead of the desired due date, in order to let responsible parties work the items into their schedules without too much disruption. And originators should plan for a shakedown period of a month, after first receiving a new feature, before it'll be fully debugged. This means that a feature-request PR submission should be made two months in advance of the ship date of the feature: one month from submission to desired delivery, and a month to shake out any problems.

There are responsibilities on both sides to meet this minimal timetable. The originator must respond immediately once the responsible party delivers the feature, to flush out any problems right away, so that any rework can be fit into the responsible party's schedule. Too often, the originator doesn't bother trying the new feature until the last minute, at which time it's too late to fix problems. The originator of a feature request is the one responsible for quickly testing it, and sending feedback to the responsible party. Plan on at least one such back-and-forth before a new feature will be finished.

On the other side, the responsible party must meet the promised delivery date, since the originator is setting aside a block of time at that date to test the feature; a delay would be inconvenient for the originator at best. And the responsible party must deliver a feature that has been tested to do what the PR specifies. There will be inevitable miscommunications, but there is no excuse for partial delivery.

Any PRs with dates closer than one month are a flag to management, that it should examine the history of the PR in question to determine what went wrong. Possibilities are that delivery quality is too low (indicated by deliveries that don't match what the PR specifies), that communication is imprecise (indicated by lengthy rework periods after a delivery, that are still generating "clarification" PRs in the final month), or that there was poor planning (indicated by initial feature requests with less than two months to the final ship date).

Gnats Usage Guidelines

When changing a PR's state so that another person must next act on it, such as a change to feedback or from there back to open, supply a reason. Particularly for rejection-type state changes, such as putting a PR into feedback without any code change, or when changing a PR from feedback back to open there must be an explanation, so that the other party can see why the rejection happened.

Non-privileged originators may not change the Responsible Party field on the new-PR submission form; all such PRs go to the administrator. Privileged originators may set the Responsible Party during submission if they have a good guess who it should go to.

For fixed PRs, report the source update number in which the fix was made as part of the feedback comment; for instance, "fixed in 123". The originator will test this on receiving the next gdk at that source update or higher. It's not necessary to produce a gdk at 123, one at 126 would do fine. Be aware that the PR is not considered off the responsible party's hands until the fix goes out to the originator. When the originator closes the PR, s/he should write "tested in 125", for better tracking should the fix later break again.

It is the responsible party's responsibility to look at all open PRs newly assigned to him/her, even undated ones, and to immediately reassign them to another responsible party if they've been mis-assigned. This is to prevent a PR going to someone who doesn't understand it and just sits on it for a couple weeks, when the proper party could fix it immediately. In theory, the responsible party ought to change undated open PRs to analyzed, just as with dated PRs, in order to guarantee this reassignment analysis. But to save busywork this isn't required as long as a responsible party has a good history of doing immediate reassignments as necessary.

When opening a PR that is related to a previous one, mention the previous PR in the comments of the new one.

Change history:
    December 14, 1996: created.
    June 12, 1998: made more generic, for non-Worlds use.
Copyright © 1996-1998, Steve Colwell, All Rights Reserved
Home page