Thanks for this analysis, Dag. In general, I think we should strive to
simplify our JIRA form. We are going in the right direction if we remove
ambiguous fields or collapse them together. We are going in the wrong
direction if we identify an ambiguity but don't resolve it. We are
probably going in the wrong direction if we add more fields without
removing others.
Some comments inline...
Dag H. Wanvik wrote:
Hi,
I have started working on the definitions. Instead of making en entire
document, I'll hand out my proposed definitions (culled from other
source or invented by me) a little bit at a time, for digestability.
I'll collect all when we are through and put them on the Wiki.
OK, first installment:
-----------------------------------------------------------------
* Guidelines for triaging Derby JIRA issues
To keep the JIRA database as useful as possible, we want the
different fields in a JIRA issue to be used as consistently as
possible. This enables quicker identification of issues with
certain characteristics of interest, e.g.
- for a release manager to check that all show stopper bugs have
been addressed before a release
- for developers, preparing short lists of bugs to look at fixing
- se we can prune the database of old bugs that are not reproducible
- so we can make different kinds of statistics to measure trends
Practice over time has shown that Derby has many fields, but
sometimes it can be hard to be sure what value to give to a
certain field due to several reasons:
- lack of immediate information: some kids of information require
further analysis of an issue to be able to determine its value,
e.g. if a bug is a code line regression or not
- not obvious fields: how should I use the priority "blocker" vs
the urgency "blocker" value? What constitutes a crash?
- JIRA provides several ways to achieve the "same thing",
e.g. sub-tasks vs. "is-part-of" links.
Furthermore, values can be inconsistent due to users filing
issues without necessarily reading the instructions (well), and
even if they do, instructions are not up to date.
Generally, the JIRA database is a tool for developers, so we should
not shirk from editing user's setting of priority, urgency. If we do
change the user's setting, we should explain in a comment why, though.
This is an attempt at clarifying meanings of fields, and also to
provide hints for filling them out. The guidelines are intended for
committers and developers to help keep usage in line.
* Title:
- Make as descriptive as possible, but try to avoid using very
long lines. It's usually better to give more detail in the
description.
- For bugs, describe the problem or symptom seen, not its solution.
Sometimes, when working on a bug, the underlying problem turns out
to be different then symptom indicated in the title. In such
cases, keep the symptom description (but it's good to make it
clearer!) since this will decrease duplicates later.
Use of keywords in the title is good, to the extent they do not
duplicate component information.
* Issue type
- "Bug" is pretty obvious.
- Use "Improvement" for improving an *existing feature*, and "New
Feature" when it is a new user functionality. Example: allowing an
alternative keyword in the syntax is an improvement, not a new
feature. Replication is a new feature, but the limit can be hard
to fix sometimes, granted.
I think this is fuzzy at the edges. Above you listed some consumers and
uses of JIRA. Would any of those consumers or users be frustrated if we
removed NewFeature and just offered the Improvement choice?
- "Task" (in contrast to sub-task) is for stuff that is not a bug,
for example code cleanups that do not result in changes in
behavior.
To my mind, the example you give could be classified as either Task or
Improvement. To me, a good example of a Task would be one of the
placeholder JIRAs which track the work done by a release manager.
However, I don't think we'd lose any important information if we
eliminated the Task issue type.
- "Test" is a bit awkward, since but we also have a *component*
called "Test" (the component "regression test failure" will go
away, being replaced by the corresponding flag).
The wording in [1] is:
"An entry regarding a test (unit, integration, system, stress
etc.) including requests for new tests."
The "regarding" wording above seems to cover all issues,
including bugs and improvements. *But*, more issue types than
"Test" are used by the "Test" component issues, though. Usage is
mixed here.
QUESTION 1: Is the issue type "Test" redundant since we have a
component called "Test"?
QUESTION 2 (if answer to Q1 is "no"): should any test component
issue *not* use issue type test, and if so, when? For "Bug"?
For "improvement"? For "new issue"? The first two of these are
common, the last is used only in three instances.
I think that Test is a Component, not an issue type. I think we should
remove this issue type.
- "Wish": is for user wishes, I think. Should mostly be reclassified
as issue type "new feature" or "improvement" if we agree it's a
reasonable wish.
I think this is another confusing, redundant synonym for Improvement.
Whack it!
* Priority
I think that just about everybody in the community has been confused by
the difference between Priority and Urgency. And not just our community.
These fields confuse other JIRA users: http://longman.deadsquid.com/?p=249
I think that Priority and Urgency are just two of the ways that people
try to express an issue's importance. I would like to move away from
subjective measures of importance. I think that the following notions of
importance are well-defined and can be regarded as facts:
o Hassle. This is the issue's importance to the person who bothered to
log it. I think we do a lousy job of tracking Hassle. In fact, we
actively clobber it.
o Recoverability. This is some generic ranking of the issue's type. For
instance DataCorruption > Crash > WrongResult > Abort > HardToUse >
Ugly. We could track Recoverability better given a little concentration.
o Votes. This attempts to capture how much users in general care about
the issue. The accuracy of this fact is dubious right now because users
don't vote much.
o Releasability. This expresses how important the issue is to the
release manager. I'm not sure the release managers handle this
consistently, but, at the end of the day, this ranking is communicated
to the dev list.
All of these facts determine whether an itch is worth scratching. A
moderate Hassle to your platinum customer may get fixed faster than a
DataCorruption which only affects someone who gives the community nothing.
I would be happy with something like the following:
1) Priority = Hassle
2) Urgency = Releasability
Extra credit if we could actually rename Priority and Urgency. As long
as they keep their original names, they will be mis-used. It doesn't
matter if we write a clear, slim primer on how to operate JIRA.
Self-revealing, intuitive controls always trump RTFM.
Listed in [1], we have (quote):
- Blocker: Show-stopper! Blocks development and/or test work. No
work-around possible. Needs to be worked on right away.
- Critical: Severe issue that potentially has a work-around but may
not be acceptable under all circumstances. Includes issues such
as system crashes, loss of data or severe memory leaks. New
features & improvements in this category are required urgently
but not ASAP.
- Major: Issue has a work-around but there is a major loss of
functionality. For new feature/improvements, this needs to be
implemented soon (but not urgently)
- Minor: Some loss of functionality. Work-around exists. For new
feature/improvements, there is no urgency with the implementation
of this request.
- Trivial: Lowest priority. No loss of functionality. No hurry to
fix/code this. Mostly a cosmetic issue like misspelled words or
misaligned text
Do we really need this much granularity? What if we pared this back to
Blocker, Major, and Trivial?
* Urgency
Nothing in [1]. My suggestions below.
- Blocker: We won't make a release if this one isn't fixed
- Urgent: Should preferably be fixed before a release is made
- Normal:
- Low: No need to hurry about this one
Note that "Blocker" is also a priority. So how to use {Priority X
Urgency} ? It is not obvious how priority differs from urgency.
A tentative definition is "Priority" is more akin to severity, that is
its related to the product code independently of popularity and
release plans etc, whereas "Urgency" is used as a scheduling tool, and
the urgency of a bug can be changed over time. These two fields are
not completely independent, I think. Please help flesh put instruction
for how to use these two!
If Urgency is basically Releasibility, then does this field need any
values other than Blocker and Non-blocker?
Thanks,
-Rick
Should the Priority definitions be revised now that we have urgency?
Note that the definition for priority "major" uses the word
"urgently".. ;-)
[1] The business of Filing Apache Derby Issues in Jira
http://db.apache.org/derby/binaries/FilingDerbyIssuesInJira.pdf
Dag
