JIRA Best Practices

How to write a good JIRA ticket

1. Before you file a bug, check that it's not already filed

Before you fill in a bug report, search through existing bugs to see if any match what you're about to report. If you've encountered it, it's quite possible someone else has, too.

If you do find a bug that seems to match yours, add a comment to the JIRA describing any additional information you can: different context or environment, new information, suspicions as to the cause...

2. Consider your audiences when writing the one-line summary

JIRAs will be read by a variety of people:

  1. those searching the database to see if a problem they've encountered has already been reported
  2. those assigned to fix a bug
  3. those reviewing bugs in preparation for releases

The one-line summary should describe the issue from a behavioural perspective: "The grommet doesn't come off when the flange is twisted," "Activating the floople causes everything to freeze," etc. The reader should be able to know from this summary whether or not what they are experiencing is already something we know about and will fix.

3. Provide details

The Description section of the JIRA should include the following:

  1. Instructions for reproducing the bug. If you have a link to a page for this, that's helpful.
  2. Additional details about the general context
  3. If the behaviour is different than expected, describe the expected behaviour.
  4. Explain implications for the larger picture.

The description is also a place to include more technical information that might be helpful to whoever tries to fix the bug:

  • any console logs or error messages
  • any details you may have tracked down while investigating
  • any suspicions as the technical cause of the problem
  • any suggestions for how it might be resolved

4. Fill in the other fields

Remember to fill in fields like the Component and the Environment.

The "Affects Version" should be the version in which you observed the problem. If you observed it in trunk, then

  • if it will be fixed as part of the next release, don't set the "Affects" version - just the "Fix" version
  • if it won't be fixed for the upcoming release, then the "Affects" version should be the upcoming release

Keeping JIRAs up-to-date

1. If you explain a JIRA to someone (or ask someone for an explanation), update the JIRA

If you had to ask the person who filed a JIRA for more information, then use that information to update the JIRA: refine the summary, add details, add instructions for reproducing, etc.

2. If you discuss the JIRA in the channel or on the list, add a link

Our Matrix Channel is logged with messages that be linked to, and the mailing lists are archived. If you use either of these venues for a discussion about a JIRA, comment on the JIRA summarizing any conclusions of the conversation and include a link to the conversation.

3. If you're reviewing JIRAs, make any necessary changes

If you encounter JIRAs that are missing a component, or if a priority seems wrong, or the Affects version needs updating, please feel free to fix them.