JIRA
JavaFX uses JIRA as its bug tracking database. Our JIRA instance can be found at http://javafx-jira.kenai.com.
Project
Use the Runtime project for FX bugs. This is the default.
Issue Types
Issues are classified by the following types:
- Bug - A defect.
- Feature - New functionality or a significant upgrade to existing functionality.
- Tweak - A minor enhancement, re-factoring or code cleanup. Tweaks are small in scope. As a rule they should be no more than 2 weeks in duration.
- Task - A work item that does not change the repository. Examples: baselining the PRD, open source approvals or architecture reviews.
- Test - A fix or update to the test suite.
- Sub-task - A sub item of any of the above.
Optimization- Deprecated - Do not use this issue type.
Many processes are different for different issue types. Unless you are a committer, submit only Bugs.
More Detail
Features get tracked against as larger work items while Bugs and Tweaks do not. Tests and Tasks may be allowed at times when Features, Tweaks or Bugs are restricted. Bugs are counted in quality metrics while other types are not. As a result it's important to get the issue type right. Calling something a Bug rather than a Feature or calling any kind of code change a Task are the most common mistakes.
API changes are not distinguished via issue type. Features, Tweaks and Bugs may all cause API changes.
Sub-tasks are often used by developers to break a complex issue into more manageable parts. As such they are a convenience for the development teams. The release team does not track at the level of sub-tasks. To make this work, however, an issue should not have sub-tasks with different Fix For versions. If an issue is so complex that it spans multiple releases, it should be broken into several separate issues.
Summary
The summary field should contain a very short description of the problem such that it is possible to read it and understand the area that is affected and what the symptoms are. Phrases such as "buttons do not work" are not very helpful. Instead, look for better descriptions like "Push button draws garbage when pressed" or "Push button fails to send callback when pressed".
Sometimes, component owners and committers will add ad hock categorization in the summary field. For example, "[ListView] List does not deselect when Ctrl+Click pressed". Another common ad hock categorization is "[Windows]" or "[Linux]" to indicate quickly that a problem only happens on a certain platform.
If you add an ad hock categorization, it might be deleted or changed later by the component owner or another committer.
Component
OpenFX is divided into components and these are used to assign default ownership of a bug report. Typically, many bugs are in 'Controls', 'Graphics' or 'Base'. If you do not know the component, please make your best effort based on the component in Code Ownership. Unfortunately, the component ownership table does not quite line up with this the choice of components but this will be addressed in future.
Affects Version
//TODO - how is this best chosen, obviously is should be the version that the person is running but is there more to it?
Description
This is the most important part of the bug. A bug that cannot be recreated cannot be fixed. In fact, committers won't make code changes without a test case that shows the problem and then shows the that problem is gone after the fix is applied.
When you submit a bug, please supply sample code that demonstrates the problem and numbered steps.
//TODO - complete this very critical section with and example
Environment
This field is used to capture the platform where you are running.
//TODO - list environments
Priorities
Priorities indicate the order in which issues should be resolved relative to a release. Priority encompasses the concepts of importance and urgency. The two concepts are highly correlated in that most of the time the worst bugs should be fixed first. There are cases, however, when an issue might be urgent but not important or vice versa.
The following priorities are available:
Priority | Urgency | Importance |
---|---|---|
P1 - Blocker | Emergency. Do it now. | Build or SWAT failures. Issues that stop 1 or more teams from all work. |
P2 - Critical | Expected for next milestone. | Basic functionality unusable. Data loss, crashes, security problems or severe memory leaks. |
P3 - Major | Expected for this release. | Major functionality unusable. No reasonable workarounds. |
P4 - Medium | Optional for this release. | Problem limited in scope or with a reasonable workaround. |
P5 - Minor | Optional for this release. | Very limited scope or with trivial workaround. |
The purpose of priorities is to make it easier to find the issues to focus on. This principle has several consequences:
- If the system is functioning properly, there should be more issues at a given priority level than at the next higher level. Think of it this way. The purpose of priority level n is to find the important stuff out of the pile of issues at priority level n+1. A priority level can't do that if there is little discrimination against neighboring levels. Or put another way, if everybody is somebody then nobody's anybody.
- The distribution of priorities should apply to future releases as well as the current release. It is not helpful to insist that everything that is not done right away is therefore a low priority. That just makes it hard to find the important stuff in the future. This is why priorities are relative to a release. (This has some limits.)
- Priorities may change over time. Neither importance nor urgency are immutable.
- Priority values are under control of the Assignee.
Labels (a.k.a. keywords, tags)
In general, teams or individuals may label their issues as they see fit. There are, however, a set of common labels that are defined project wide. These labels should be used as defined and should not be used for other purposes.
//TODO - list of common labels