Tips For Filing Apache Derby Bugs

This document is suggested reading for anyone who wants to enter a bug against Derby. It explains how to go about filing a bug and what information you should provide to make the bug entry useful to a developer attempting to fix it. For information on filing other issues in Jira (enhancements, improvements etc.) and for a detailed description of some of the less understood concepts and data fields in Jira, please read the document titled Apache Derby Issues in Jira [doc, PDF].

Derby issues are maintained at http://issues.apache.org/jira/browse/DERBY. Suggested actions to take before/while filing a bug are listed in the sections below.

You may access Jira at

http://issues.apache.org/jira

If you do not have a userid, create one. A "Signup" link has been provided on the login page. There are 2 levels of access to Derby issues in Jira, "user" access and "developer" access. A "user" may open a bug but will not be able to edit/update/assign it. This requires "developer" privileges. If you think you will need to edit/update a bug entry, please send an email to derby-dev@db.apache.org requesting that you be added in to the "derby-developers" group in Jira.

Before filing a new bug, it is recommended that you first search Jira to verify that it has not yet been reported. Jira offers various fields (and combinations thereof) that you can search on. You will probably benefit the most by searching on keywords that are relevant to the bug you are intending to report. For more details on how to search, see the document titled Filing Apache Derby Issues in Jira.

If the bug you are intending to report is not already logged in Jira, it may be a good idea to post a query to the derby-user@db.apache.org mail list asking the following:

- is your bug really a bug (or a restriction, feature request etc)

- has anyone else noticed this bug and if so, under what circumstances

- can anyone suggest a workaround for the problem

- if relevant, why you think the bug is a "blocker" (highest priority)

Note: Posting to the mail lists should not be seen as an alternative to filing the bug in Jira. This step may be viewed as optional, however you should at least search Jira for an existing bug report.

When you post a new bug to the mail lists, please pay attention to the following details that make it a "useful" post. These simple guidelines help avoid poorly filed/described bugs:

- Attach the output of "sysinfo" to your bug description. This contains important version, CLASSPATH, build, JRE and platform information that will be useful to a developer trying to reproduce and resolve the bug. Please run the following command in the exact same environment your Derby application ran under when the bug was detected

'java org.apache.derby.tools.sysinfo'

When you set your application environment manually, make sure you do the very same setup before running sysinfo. On the other hand, when the application sets up the environment, you need to run sysinfo under the application environment to ensure that accurate information is captured by sysinfo.

- Give clear bug reproduction information as part of your bug entry. This could be in the form of a script, a program, code snippet or step-by-step instructions.

- Include any relevant output from the derby.log file. If this information is too confusing for you to understand and the file isn't too big, you may want to attach it to your bug entry

Provide error information such as SQLSTATE and nested exceptions reported by Derby. Usually, Derby would generate chained exceptions (nested), so you should write applications that traverse the chains with the getNextException() method call in your exception reporting code. If you are not using a JDBC application, you should report the series of nested exceptions (if generated) displayed on your error console.

There are 4 special flags that can be set; each has its own effect and use.

• Patch Available: indicates that a patch is available for review and/or commit. Gets picked up by daily automated mail.

• Existing Application impact: an existing application can be impacted by the solution to this issue (not the issue itself).

• Regression: the behavior described is worse than in previous versions/builds.

• Release Note Needed: indicates a releaseNote.html is/should be attached. The releaseNote.html will be automatically included in the RELEASE-NOTES.html at release time when this flag is on.

As the submitter of a bug, it is your responsibility to verify a bug fix and "Close" the issue. Once fixed, a developer marks the bug as "Resolved" with a resolution of "Fixed". You need to then go back and "Close" the issue, provided you agree the bug has been fixed. If the resolution of the bug is something other than "Fixed" and you disagree, or the fix submitted did not really resolve the issue, you need to "Reopen" the issue. Please add relevant comments in Jira when doing these operations. See the document titled Filing Apache Derby Issues in Jira for additional details.

Note that once you file your bug, Jira will generate a notification email to the derby-dev@db.apache.org mail list.

You may want to read the document titled Filing Apache Derby Issues in Jira for additional details on the following concepts:

• How to search Jira for an existing bug

• How to Resolve/Close a bug

• The seemingly obvious and not-so-obvious fields in Jira such as Priority, Components and Resolutions

• Guidelines for workflow of issues in Jira

• What to do to avoid a poorly constructed bug entry

Last updated: May 9, 2006