Overview

JavaFX uses JIRA as its bug tracking database. Our JIRA instance can be found at http://javafx-jira.kenai.com.

The most important thing you can do when entering a bug report is to ensure that the person who investigates it has enough information to recreate it.  The best way to ensure this is to provide:

• a complete code sample
• a set of steps (numbered is best)

Fortunately, JavaFX programs tend to be very short to providing a complete example, including main() is not particularly difficult.  Certainly no code is released without a test case that demonstrates the problem and that the problem is gone as a result of the fix.  By numbering the steps in a description and stating what you should see at each step, it helps to focus the reader.  Of course, not all problems can be described in this manner but a surprising amount can.

Here are some other things that are helpful in a bug report:

• a screen shot of the problem
• the exception or crash log
• platform specific information (ie. "only happens on Windows")

IMPORTANT:  Bugs that are missing the information needed to recreate them will be closed as 'Incomplete'.  The message that you should take away from this is "there is more work to do before this bug can be processed" and not "we do not care that there is a problem".

Project

Use the Runtime project for FX bugs.  This is the default.

Issue Types

Issues are classified by the following types:

1. Bug - A defect.
2. Feature - New functionality or a significant upgrade to existing functionality.
3. 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.
4. Task - A work item that does not change the repository.  Examples: baselining the PRD, open source approvals or architecture reviews.
5. Test - A fix or update to the test suite.
6. Sub-task - A sub item of any of the above.
7. Optimization -  Deprecated - Do not use this issue type.

IMPORTANT: Many processes are different for different issue types.  Unless you are a committer, submit only Bugs.

More Detail About Issue Types

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.

The best way to ensure that a bug can be recreated is to provide:

• a complete code sample
• a set of steps (numbered is best)

Here is an example:

//TODO - find good example in JIRA and point to it

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:

The purpose of priorities is to make it easier to find the issues to focus on.  This principle has several consequences:

1. 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.
2. 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.)
3. Priorities may change over time.  Neither importance nor urgency are immutable.
4. 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