WTP Bugs, Workflow and Conventions

Introduction and Purpose of this document

Our WTP Bugs are tracked in the Eclipse bugzilla system.

There is a main "Web Tools" classification category, with, currently, three subclassifications (called "Products" in bugzilla): Web Tools proper, for released components; and others for subprojects or components that are incubating (currently AFT, and Java Server Faces, and soon JPA).

The purpose of this document is not to repeat or contradict the normal bugzilla help documentation, but simply to supplement it, and be explicit about conventions we in WTP use that are not part of the bugzilla system per se.

See also https://bugs.eclipse.org/bugzilla.html for general information about Eclipse and bugzilla.

Workflow

The following are a guide to the day to day work that component leads and bug owners follow.

Moving from "inbox" to having an assignee (owner)

When a bug is first reported, it is put in the "inbox" of the component that was specified.

Relatively soon after that (e.g. within one week) component owners should do initial triage, and specify a specific person to own the bug. This initial triage is just an acknowledgement that it appears to be a valid report, and that it is in the right component. Things like priority might be assigned at this time, but, that can also be done later.

Based on severity, priority, and the bug owner's time constraints :( the owner will further triage or investigate the bug, ask clarifying questions, try to reproduce, etc.

Meaning of the assigned state

Once someone starts actively working on a bug, to produce a fix, they should put the bug in the "assigned" state. That way, other committers know they should not also work on it. If a bug is not in an assigned state, other committers are free to assume ownership of a bug, if, for example, it is related to other bugs they are working on, or, they happen to know about that area of code due to working on it before, etc.

Meaning of the target field

The target field should be assigned once the owner is relatively confident the fix will actually appear in that milestone. In other words, its not for long term planning, but more for short term planning and historical checking of "what's fixed" in a particular milestone.

The target field can, though, be used for one form of "mid-range" planning. Our usual targets contain the release and the milestone, such as "2.0 M3". Those are the specific targets that should not be set until it is pretty clear the fix is going in that milestone. But, there is another target that represents the whole release "2.0". This can be used for "midrange" planning, in that committers for a component, if it helps their planning, can assign a bug or feature request to "2.0", which would mean simply it is their plan to fix that release. It is not a "committed" item, but helps some teams arrange work-flow, assignments, expectations, etc. And, just because the target field is unassigned does not mean it will not be fixed in the next release ... just maybe hasn't caught anyone's attention yet, or its "unknown" how important it is, pending more investigation. It would be wrong for committers to just blindly assign all unspecified targets to the "2.0" target. It should only be for things which are explicitly being planned for. By the end of the release, there should be no general ("2.0") targets left, either having been delivered in a particular milestone, or, explicitly decided it could not be done after all and changed to 'unspecified' until the next planning cycle.

Meaning of the version field

The 'version' field is considered too ambiguous and used too inconsistently to be of much value ... but, there is a pattern that is supposed to be followed. When someone reports a bug, they are supposed to mark the version as the version they found the bug in, as close as possible (but, they usually need to give the exact build id of the version they were using, to be meaningful). Then, when fixed, the bug owner should change the version to the version the bug was fixed in).

Meaning of Priority and Severity

As stated in the Bug Reporting FAQ

Severity is assigned by a user and describes the level of impact the bug is having on them. Priority is assigned by the developer and describes the importance a developer places on fixing the bug. P1 is the highest priority, P5 is the lowest.

Bugzilla's own documentation gives a general definitions of priority and severity which is pretty much what we follow in WTP. But we provide our own Conventions of bug priority and severity. It is useful to help committers to be consistent, but also useful to point bug originators to, if they seem to need some guidance on how to be consistent with our conventions.

Conventions of embellishments

Status Whiteboard: This is pretty much for each component to use as they see fit ... usually marking short term notes of "needs review", etc., pretty much characterized as communication with other team members.

Keywords: committers should set these "built in" keywords accurately: (e.g. 'api', 'performance'), and if there is a built in keyword, there is no need to be redundant and specify the same thing as a summary keyword.

Summary keywords: These are the words or phrases contained in square brackets in the bug's summary line. Sometimes, components will use their own conventions to allow "sub categories" of bugs for their own book keeping (for example, "[project creation]"). But, the following list are project-wide conventions. Its not necessarily exhaustive, but we'll try to keep this list accurate. Note: in the event more than one summary keyword is desired, they should each be contained in square brackets, such as "[hotbug][project creation]". (Their order not being significant, and case is not significant).

[internal api]

this marks a bug report where our WTP code calls a non-api method of a prerequisite class.

[API Request]

this marks an enhancement request where the originator is letting us know that to accomplish some function/extension, they need to use some of our internal non-API methods.

[api]

this marks a bug in the "API nature" of an implementation or its documentation. It may signify, as examples, cases were an implementation does not meet spec, or a spec is not unambiguous.

The meaning and methods of verification

FIXED to VERIFIED

The ideal, preferred workflow is for the originator to verify a bug is fixed shortly after its introduced into a build. Ideally the build ID (or at least approximate date of build)will be included in the verification note.

For old bugs, opened on previous releases, verification normally means "works on current release" unless otherwise noted (that is the previous release may not be fixed and may never be fixed ... unless otherwise noted).

The component or project leads have the discretion to mark a bug as "closed" if it has been in the fixed state for a very long time (such as 6 months) so it can pretty clearly be assumed fixed. Naturally, the originator can re-open (or, open a new bug).

DUP to VERIFIED

verifying a "duped" bug means the originator is simply agreeing that its a valid dup ... not that its necessarily fixed. The originator should be added automatically to the CC list of the dup, and they are welcome to verify that once its marked as fixed.

INVALID or WORKSFORME to VERIFIED

the originator is simply signifying they see the point and agree. If the originator does not agree or does not see the point, typically some polite discussion can be carried on in the bugzilla entry without necessarily re-opening.

LATER or REMIND

while these are (unfortunately) sitting in a "resolved" state ... they are resolved just temporarily and it is not meaningful to mark them as "verified". The component or project leads have the discretion to mark a 'remind' bug as "closed" if it has been in the 'remind' state for a very long time (such as 6 months) so it can pretty clearly be assumed no answer is coming and must not still be a problem. Naturally, the originator can re-open (or, open a new bug).

VERIFIED to CLOSED

the typical workflow is for the component lead (or project lead, or QA Contact) to move a bug from a 'verified' state to the 'closed' state and simply signifies they agree the bug has gone through a valid workflow, or that the bug entry is no longer helpful, constructive, or needed. Remember to not CLOSE a bug that is marked LATER, and remember to only close bugs marked REMIND if a sufficient amount of time has elapsed (e.g. six months, spanning a major release).

The meaning of "Future" milestone target

Assigning a milestone target of "Future" means the bug or feature request has been fully evaluated and a decision made that it can not be contained any time soon ... such as not in the next yearly release ... so will be marked as "Future". This aides committers so they can filter out "future" bugs when then are looking for bugs to evaluate, as they have already been evaluated. It also aides the community and reporters as then they have a bit more status about the bug. However, there should not be any "mass update" simply to assign untargeted bugs to "Future". An untargeted bug often means "future" in reality, but it perhaps has not been fully evaluated or received much attention yet. A mass update, without full evaluation, would water-down the meaning of "future" and make it less useful as a bucket to put bugs that have been fully evaluated.

Similarly, there should not be any mass updates to un-target a "future" bug or enhancement request. But, naturally at the beginning of a release planning cycle, all 'future' bugs should be re-examined to see if it should be targeted more specifically.

What to do with bugs that need more information (aka "remind")

In the past, the resolved state of "remind" was sometimes used to mean the assignee was waiting for some more information from the originator, perhaps for example, more information on how to reproduce, or a log file, or similar.

Since "remind" will (probably) not be part of bugzilla states in the future, the following is recommended instead:

• If the bug can not be reproduced with the information given, simply mark as "worksforme" with some king encouragement to provide more exact steps to reproduce.

• If the bug can't really be understood without more information, then it's fine to simply ask for the information and at some point, either immediately, or after a short period of waiting (such as a few weeks), mark the bug as "invalid" as it's incomplete or not understandable, again, with some kind encouragement to re-open and perhaps pointers to documents such as FAQ_How_do_I_report_a_bug_in_Eclipse?