Jira issues are central to the development processes here in Atlassian. We get issues submitted from many different sources — from inside the development teams, from sales, customer advocates, and of course we get quite a few reports directly from customers.
Filing effective issues is incredibly important. Every product has a lot of issues in the database, and a lot more get filed every day. The more accurate detail is in each issue, the more efficiently we can deal with them, and the more likely it is that the issue will be resolved sooner.
This blog entry was originally posted to the internal Atlassian blogs (powered by Confluence) as a guide for the sales and advocate staff, but I figured it might be useful for a wider audience, both for anyone who might need to submit bugs to Atlassian, or as a reference for anyone filing Jira issues inside your own organisations.
Following these steps might seem like a bit of work, especially when you’re in a hurry, but remember that if you don’t do it when you file the bug, _someone else will have to do it later_, and they won’t have the advantage of knowing what you’re talking about.
h3. Don’t use our issues as examples.
Developers tend to file issues in short-hand. They’re memos to ourselves, or to the guy on the next desk who we’ve already explained the problem to in detail for the last hour.
Even then, developers should probably avoid writing quick-and-dirty issues. What happens when priorities change, and the problem isn’t looked at for the next six months?
h3. Make sure you search for duplicates
There’s no need to go overboard. Sometimes duplicate issues are hard to find unless you know what you’re searching for in advance. That said, _please_ do a quick search first on the key words in your issue, and make sure you’re not just repeating what has already been reported.
If you find your issue is already in Jira, add a comment to the existing issue instead of creating a new one.
h3. Always Choose a Component
Every Jira issue can be placed in one or more components. The component is the *second most important part of the issue* after the summary, and the most common thing for reporters to skip entirely.
If you don’t put an issue in a component, chances are it will drop to the bottom of a very dark barrel, and never be found again.
If you can’t find an appropriate component for your issue, try picking the closest one that _almost_ matches. You’ll be better off doing that than picking no component at all.
h3. Pick a Good Summary
When we’re looking through lists of lots of issues, the summaries are all we have to go on in order to understand what an issue is about. This means that you should err in favour of putting too much information in a summary, rather than too little.
Bad: _Space export doesn’t work_
Good: _Space export fails with NullPointerException when performed by the anonymous user_
Bad: _Administrator attachment control_
Good: _Allow configuration of maximum attachment sizes per space or per page_
h3. Write a Detailed Description
h4. When Filing a Bug
There’s a very simple, universal formula for bug reports. Every bug report must include:
# Detailed steps to reproduce
# What you expected to happen
# What happened instead
Steps to reproduce should be written in terms that a monkey could follow: “Create a new Confluence page called Blah. Insert the following text: “bq. I like cheese”. Set page permissions to “Me”. Click save.”
Also, you must *always* fill in the “Affects version/s” field when filing a bug, so we know in which version of the product the bug occurred. That helps developers track down the bug, and it helps support find out who else might be effected by it.
h4. When Filing a Feature Request
Detail, detail, detail, context, context, context.
Tell us where the feature request came from, as well as what it is. Tell us _why_ you want the feature. If the request comes from an email or IM exchange between co-workers, paste that into the issue too!
Knowing why a somebody wants something done is almost as important, in terms of scheduling and planning features, as knowing what they want. Sometimes it’s more important, because often by knowing why somebody wants a certain feature, we can deliver them a better solution that they’d never even thought of, or we can aggregate a bunch of related requests into an über-solution that makes everyone happy.