How to Write a Good Bug Report
GPII uses JIRA for managing bugs, enhancements and feature requests. This document explains how to describe issues in a way that makes it easier for developers to understand and reproduce issues, and how to test code fixes.
In order to report issues, request a JIRA account and log in.
Once you are logged in, follow these steps:
- Find out if the issue you encountered has been reported before:
- If the issue has been reported before and the issue is still open, you can add a description of how you encountered the bug (see guidelines under "Describing the issue", below);
- If the issue was reported in the past and closed, you can reopen it and describe how you encountered the issue. (Alternatively, it is possible to create a new bug and link the old one with the new one.)
- If the issue is new, you can report it by using the "Create issue" link at the top of the page.
Types and Severity of Issues
The JIRA setup used by GPII distinguishes between several types of issues. The most important ones are:
- Bug: for defects;
- Improvement: for both enhancements (i.e. improvements to existing functionality) and feature requests (functionality that is not available yet).
Issues can be assigned one of the five priority levels:
- Blocker: highest priority; this issue must be fixed before the next release (or the user tests).
- Critical: e.g. application crash, loss of data.
- Major: major loss of function.
- Minor: minor loss of function.
Describing the Issue
The "Description" field should contain the following information:
- A summary of the issue;
- A section that explains how a developer can reproduce the issue, as a series of steps, and what output should be observed;
- A section that describes the desired behaviour;
- Current workarounds or mitigation methods (if applicable).
Use heading level 4 for each of these sections. You can do this in JIRA by putting
h4. in front of the heading text.
For complex issues, see the section on relationships between issues.
Component and Assignee
Identify the component (or components) to which the ticket applies. Each component has a "Lead" (see for example the list of GPII components) who is also the default assignee. You should always assign the ticket to the most appropriate team member, but if you do not know who to pick, the system will take the default assignee. If necessary, this person can re-assign the ticket to somebody else.
You can also define the relevant component(s) after creating the ticket; see the "Details" section on the ticket's page.
The summary describes the issue in (at most) a few sentences, i.e. what the problem is and where it can be found (device, platform, component, ...).
Steps to Reproduce the Issue
This is a detailed description of the issue, i.e. a precise explanation of the steps that someone else would have to take to reproduce the problem. This section also includes the result you found (e.g. component X crashed, error message Y appeared, etc.).
Make sure that you include information about the platform (e.g. Windows 7, including 32-bit or 64-bit) and all other dependencies.
The steps are typically formatted as a numbered lists. Use the hash sign (#) to create list items in JIRA.
An example of a list of steps can be found in issue GP-112.
The result or behaviour you expected, in other words, what the system should do if the issue were not present. (This information can also be included in the previous section instead of in a separate section.)
This optional section describes anything that people can do to work around the issue, if any workarounds exist.
Relationships Between Issues
Issues can be related in several ways. In order to define such relationships, choose "Link" in the menu "More actions" at the top of an issue page. Some examples of links:
- Duplicate: this is typically used to mark a new issue as a duplicate of an older issue.
- Depends on and Is blocked by: these are used if another bug needs to be fixed before the current bug can be fixed.
When you add a link from one issue to another issue, JIRA automatically adds a link back from the other issue to the first one, so it is not necessary to edit two different bugs that share a link.
When an issue is particularly complex, it is possible to create sub-tasks. This effectively turns the issue into a "meta-bug". To do this, go to "More actions" and choose "Create Sub-Task". For each sub-task, use the same description guidelines as above. (SP-29 is an example of a meta-bug.)
Status and Workflow
At all times the assignee is responsible for keeping the JIRA alive and moving it forward. In case of a "Needs more info" status, it is the responsibility of the reporter to provide this information.
The below list explains the possible states of the JIRAs. It's not chronological - i.e. it's possible to for a JIRA to have the following workflow: Open->In Progress->Resolved (Fixed) in case a pull request is not relevant for the JIRA in question.
- A new issue is Open when it has been reported and no fixes have been merged into the relevant branch yet.
- An issue moves to Needs more info when there is not enough details in the JIRA to reproduce or fix it. It's generally the task of the reporter to provide the extra information required.
- An issue moves to In Progress when work has started on it and no pull request is pending
- An issue moves to Pull Request when a contributor has submitted a pull request to a github repository - A link to the pull request should be added to the JIRA
- An issue moves to Resolved when:
- A fix submitted by a developer has been merged into the relevant branch (i.e. simply submitting a pull request on GitHub does not resolve the issue) - or the JIRA is fixed by other means - resolution should be Fixed - if a pull request has been merged, the commit hash on github should be linked
- The issue cannot be reproduced - resolution should be Cannot Reproduce
- The new issue is a duplicate of an existing issue - resolution should be Duplicate
- An issue moves from Closed with a resolution of Fixed when
- Integration testing or "pre-pilot testing" shows that the issue does not occur again (this is currently not happening to a very large degree) - this cannot be done by the owner of the JIRA - in the general case this happens when Integration testing or "pre-pilot testing" shows that the issue does not occur again. If neither applies to a particular JIRA, the reporter of the JIRA should be the person closing it when they're satisfied with the fix/resolution.
In order to make sorting and retrieval of issues easier, you can specify the component(s) to which an issue applies (currently: "General Arch", "General Pilots", "Matchmakers", "NPGT"). In addition, you can also add labels, i.e. select one from the list and/or add a new label.
You can notify other JIRA users about updates in comments by using the syntax
[~username]. As soon as you start typing
[~, autocompletion suggestions will appear. (See also the use of
@ to e-mail issues.)
- Infusion Developer Guide: Using JIRA.
Issues related to Fluid Infusion projects (UI Options, the Model Transformation System …) need to be submitted to Fluid's issue tracker.
- Infusion Documentation: JIRA Best Practices.
- Document Foundation: How to Report Bugs in LibreOffice.
- Mozilla Developer Network: Bug writing guidelines.