GWT Bug Triage & Routing Process

This document describes each label and state in the GWT Issues Tracker, and defines what they mean and how they are expected to be used. It also lists which team members get assigned which types of bugs by default, and describes the bug triage guidelines.

Goals

• SIMPLICITY!
• Casual readers of the Issue Tracker should be able to immediately understand the state of a bug without extensive explanation.
• Project leadership must be able to easily make use of the content in the Issue Tracker to guide the project.
• Engineers must not be inordinately burdened by the Issue Tracker.
• The Issue Tracker configuration must not contain any misleading or unused fields or labels.

Non-Goals

• We will not conform our behavior to the Issue Tracker; we will conform the Issue Tracker to our behavior.
• Corollary: we will automate where necessary.
• Ease of use by Engineers is not a goal. That is, features that make usage easier for Engineers take a back seat to features that make it easier for users.

Assumptions/Generalizations

• The Issue Tracker is now organized along roughly the same sub-teams that now group the Engineers to allow category-specific triage.

Categories

The category describes which aspect of the system is affected by the Issue. This is less about describing the Issue, and more about routing it. That is, the goal is not to describe the Issue, but rather to indicate the sub-team whose attention is required by the Issue. Thus, it does not matter if an Issue is categorized as "RPC" but actually cross-cuts over RPC and HostedMode; it is simply being directed to one sub-team or the other (who may re-Categorize as appropriate.)

The assignment of a Category indicates that the Issue has been triaged. For ease of remembering the process, rule of thumb #1 is: If no Category is set, the Issue has not been triaged!

Additionally, when setting a Category, the triager should also set the email address in the Cc: field of the Issue according to the table below. Note: this is not to be put in the Assignee field, but rather the Cc: field. The intent is to guarantee that the sub-teams have at least one representative receiving notification about bugs aimed at them.

Status Values

The status values indicate the progress of the Issue toward being implemented. The status does not imply anything about the importance or eventual fate of the issue. The meanings of the key status values are:

• New - Not yet started (Note: does not mean "untriaged".)
• Accepted, Started - for use by engineers per personal preference. No global meaning. Note that "Accepted" is not the same as being "Planned".
• Started - the assigned engineer has begun working on the Issue.
• ReviewPending - a patch for the issue is complete, and pending peer-review; fix is not yet committed. A label indicating the specific peer reviewer will also be set.
• FixedNotReleased - coding on the Issue is complete and committed, but the revision containing the fix has not yet been put into a packaged release.
• NeedsInfo - the Issue requires additional information from the reporter or a commenter. No further action will be taken until the additional info is provided.
• Fixed - fixed, and available in the packaged release indicated in Milestone.
• NotPlanned - the Issue will receive no further attention.
• Invalid - bug is erroneous, incomplete, ambiguous, etc.
• Duplicate - bug is a duplicate of an existing bug.
• CannotReproduce - The issue could not be reproduced at all.

The other status values are self-explanatory. Again, note: a bug being marked as Started, FixedNotReleased, etc. does not imply it will be in the next build. Only the Milestone indicates information pertaining to releases.

Types

This field is used to denote whether an Issue is a Bug or a Request for Enhancement (read: Feature). It can also denote non-code bugs (such as documentation issues.)

Priorities

The Priority field is a measure of how important (and therefore likely) it is that an Issue be resolved in the next release. It is not a measure of the severity of an Issue. For example, most Compiler bugs will be marked as Critical since a strong effort is generally made to make sure such Issues do not carry over to the next release. However, a hosted mode crash bug is high severity but might very well be Medium or Low priority if its occurrence is rare, thus allowing project leadership to defer the bug to a future release. It is even possible (though probably rare) for a High priority bug to be marked as NotPlanned for the next release.

In a nutshell: Priority indicates whether the Issue should be a blocker for the next release, not the relative importance or severity of a bug.

Milestones

Milestones correspond directly to packaged releases. They generally are either Release Candidates (RCs), or the final release for a given version. In the Issue Tracker, RC labels will only exist as long as the final version has not yet been released. For example, if the project is on the 1.3 release cycle, then there may be a "1.3 RC1" and "1.3 RC2" release, as long as there is no "1.3" (final) release milestone. As soon as a Release Candidate is promoted to the gold/final release, the Issue Tracker will be updated so that all Issues marked as Fixed in a given RC will be reset to Fixed in the Final release. (That is, all RC Issues will be promoted to the final release milestone.) The purpose for this is for clarity to casual users of the system seeking to determine which Issues are resolved in a given release, and for generating Changelogs.

Unless there are two releases pending at once (such as a bug-fix branch release, and a next-gen trunk release), there may only be RCs for one release at a time in the Issue Tracker.

Examples of "legal" Milestone sequences in the Issue Tracker:

• 1.1, 1.2, 1.3RC1, 1.3RC2
• 1.1, 1.2, 1.3

Examples of "illegal" Milestone sequences in the Issue Tracker:

• 1.1, 1.2RC, 1.3
• 1.1, 1.2, 1.3RC, 1.3

Issues are attached to a Milestone if and only if they were (or will be) present in the packaged binary corresponding to that Milestone. Put another way, if an Issue does not have a Milestone set, it will not ship in any currently-planned release. Conversely, users can use the Issue Tracker UI to search for a Milestone they are interested in, and be confident that the results of that search are an accurate description of the contents of the corresponding release (remembering that "Priority" is an indication of the likelihood of its successfull inclusion).

Stable-Release Milestones

As a matter of policy, no bug may ever be released in a final release that was not vetted in a Release Candidate for a packaged release. (That is, the GWT team will not "slip in" a bug fix between an RC and a final.) Thus, any new bug which is filed and triaged against a pending RC will implicitly require a new RC Milestone be created.

Put another way: a final release is always bit-identical to the previous Release Candidate (excluding practical issues such as version strings, release notes, etc.)

This results in this development cycle:

1. Users file Issues.
2. Project leadership identifies Issues to be included in next release, and flags those Issues as Milestone = RC1.
3. GWT Engineers fix the Issues, and publish the RC1 build.
4. Users file Issues against RC1.
5. Project leadership verifies bugs filed against RC1, and if confirmed, marks them as Milestone = RC2.
6. Repeat previous 3 steps (incrementing the RC counter) until no new bugs are filed/accepted against the current RC.
7. Latest RC is promoted to final.

Planned Milestones

Most of the time, GWT will be releasing stable versions from a branch while doing deep/intrusive development on the "trunk" or "head" code. Project leadership will follow essentially the same process for trunk releases as for stable releases. However, because the next version number is not necessarily obvious, rather than mark Issues intended for trunk releases with a specific version, they are marked with a Milestone of "Planned" to denote that they are planned for a future release.

This is a concrete indication that the Issues will be resolved in the first release that takes place after the current stable branch is retired. (It is not a vague indicator that it will be fixed some day; Issues in that vague state are simply assigned no Milestone at all.)

Thus, for trunk/development releases GWT has the following development cycle:

1. Users file Issues.
2. Project leadership identifies issues that need to be fixed soon, but that are inappropriate for the current RC, and flags those Issues as Milestone = Planned.
3. Engineers begin coding on Planned issues, but this work will not hold up the current release cycle.
4. When the current release cycle is completed, project leadership determines the next version number, and moves all Planned issues to a new RC Milestone for that version.
5. A new release cycle begins, and the "Stable-Release" process takes over.

Life Cycle of a Bug

Here is an illustration of the life cycle of a bug. All version/release numbers, flags, etc. below are purely hypothetical.

• A user files an Issue as number 1234.
• The new Issue is triaged:
• The issue is marked as Type = Enhancement, and Category = HostedMode.
• The HostedMode sub-team contact is attached to the bug as a Cc:
• Project leadership reviews extant Issues, including 1234, and determines that Priority = High.
• There is no open Release Candidate release cycle, so  Issue 1234  is marked as Milestone = Planned so it gets included in the next release cycle.
• An Engineer is assigned to work on  Issue 1234 :
• The Assignee field is updated to the appropriate Engineer.
• The Engineer sets Status = Started once she actually begins working on it.
• When the work is complete, the bug is marked as Status = FixedNotReleased.
• Project leadership begins a new release cycle, for version 1.7.
•  Issue 1234  is moved from Planned to Release_1.7_RC1.
• For  Issue 1234 , Status = Fixed
• RC1 is released.
• Two more release candidate cycles are made, resulting in RC3.
• RC3 is promoted to final.
•  Issue 1234  is moved to Milestone = Release_1.7.
• The Milestone "Release_1.7_RC1" (and ...RC2 and ...RC3) are deleted from the Issue Tracker.

Rules of Thumb About the Process

Here are some observations, consequences, and warnings about the process as described above. These are supposed to be easy to remember to help everyone develop an intuition about how the process works:

• If the Category is not set, the Issue has not been triaged.
• If the Assignee is not set, the Issue is not being worked on (and no one is responsible for it.)
• If the Milestone is not set, the Issue is not on the team's immediate radar.
• Priority is relative to the Milestone (as in, the same issue can have a different priority across releases).
• If Status is not set to FixedNotReleased or Fixed, the work is not complete.
• If Status = FixedNotReleased and Milestone = Planned (or is not set) then the Issue is resolved in trunk in Subversion.
• If Status = FixedNotReleased and Milestone = an RC release, then the Issue is resolved in that RC distribution (or will be once the RC is available.)
• If an Issue is in Status = Fixed but Milestone is not set to a released build, the Issue is in an inconsistent (illegal) state.