Effective problem reports and feature requests are the most likely to be resolved correctly and quickly. These guidelines explain how to provide the details necessary to ensure the problem or new feature is addressed as quickly and correctly as possible.

Principles

• Be precise in every detail – especially where it comes to a user interface, refer to the controls by the text they exhibit, such as the OK button, the Assigned To: field, and so on.

• Be clear – document exactly what set of steps are needed so that others can reproduce the bug; include every step that is needed to reproduce the problem, but leave out any “unneeded” steps or actions.

• Create one request per problem or feature desired – combining problems or features only confuses the issues. When in doubt, write up different sets of repro steps as different requests/reports.

• No problem is too trivial to report; small problems or features needed may actually hide big ones.

Preliminaries

1. Avoid entering duplicate requests by first searching Bugzilla (for a problem report or enhancement request) or by checking previous email threads for previous similar feature requests.

2. Where possible, reproduce your bug using a recent build of the software in order to determine whether it may have already been fixed.

3. Clearly separate fact from speculation – clearly state what is known (reproducible) separately from what is predicted or extrapolated.

Reporting a Problem

There are three main areas that need to be clearly defined in order to create an actionable bug report:

1. VERSION TESTED: What version of the product or products were used when the problem was seen? Be as specific as possible, preferably down to the version identifiers with build timestamps.

2. REPRO STEPS: How did you reproduce it, and how can the developer?

   1. What actions did you take to encounter the problem? Include every step that is needed to reproduce the problem, while removing any extra “unneeded” steps or actions. Yes, you may need to check it multiple times to figure this out.

   2. What conditions or configurations of the product contributed to the problem? Yes, you need to check and see if this “always happens” or only happens under certain configurations, with certain files, or after certain changes have been made (for example). If any input files are needed to reproduce the problem, please provide it/them.

3. PROBLEM STATEMENT: What is wrong?

   1. What behavior did you encounter that you believe is incorrect? Avoid vague statements like “It is broken.” If at all possible, please provide screenshots of any and all output windows that are relevant to the problem.

   2. What behavior do you believe should have been encountered instead? Be as specific as possible, and avoid vague statements like “It should work right.”

Requesting a Feature

There are three main areas that need to be clearly defined in order to create a feature request that can be designed and implemented:

1. PROBLEM STATEMENT: What exactly is the problem that is to be solved? Avoid giving a description of a desired implementation or solution, but rather provide a “use case” that describes what you or a user need to accomplish.

   1. State what functionality is actually needed by describing the problem itself without describing “how” to solve it. Often there are many possible ways to solve a problem, and designing and implementing the “best” solution is best done by the developers.

   2. State if there are any existing workarounds or alternative solutions to the problem.

   3. Define at what point in using the existing product the new feature is needed.

   4. Define why the new feature is needed (what makes the new feature better than any existing workaround or alternative).

   5. State who experiences the problem as precisely as possible. Be as specific as possible about the use case so that the design and implementation can meet the stated need.

2. GOAL: When is the new feature needed by? Again, be as explicit as possible.

3. IMPACT: What is the predicted impact if this new feature is not implemented by the goal date?

 

---

BUG REPORT OUTLINE

Submit the details outlined below either directly or in the Description field of a Bugzilla entry

 

PRODUCT AND VERSION WHERE THE PROBLEM WAS ENCOUNTERED:

 

STEPS NECESSARY TO REPRODUCE THE PROBLEM:

1. <put steps here in the order in which they are to be performed to reproduce the problem>

2.  

 

PROBLEM STATEMENT:

• What does it do that it should not?

 

• What does it not do that it should?

 

---

NEW FEATURE REQUEST OUTLINE

Submit the details outlined below either directly or in the Description field of a Bugzilla entry

 

PROBLEM STATEMENT (What problem needs to be solved?):

 

GOAL (When is the new feature needed by?):

 

IMPACT (What is the predicted impact of NOT having this new feature added by the goal date?):