Child pages
  • JIRA usage guidelines

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Corrected links that should have been relative instead of absolute.

Welcome to our guidelines regarding creation of JIRA issues.

JIRA issues are central to the development processes for all our products here in Atlassian. We get issues submitted from many different sources: from inside the development teams, from customer advocates, and of course directly from customers. We greatly appreciate you taking the time to submit issues, as your feedback helps us to continually improve our products.

Filing effective issues is incredibly important. Every product has a lot of issues logged in JIRA, and many more get filed each day. The more accurate details there are in each issue, the more efficiently we can deal with it, and the more likely it is that the issue will be resolved sooner. The following steps will assist you in filing effective issues.

Did you come to the right place?

We maintain this instance of JIRA to track improvement requests and reproducible bugs. This instance of JIRA is not optimised for questions and problems. We employ a team of highly specialised support engineers who will gladly help you with problems, usage questions, etc. They look at your specific environment settings, analyse your logs, and dig deep into your issues. The support team's JIRA system can be found at http://support.atlassian.com.

Search for duplicates

With thousands of customers, and a huge collection of improvement requests, new features desired, and bugs reported, chances are that your issue has been logged already.

Before filing a new issue, try searching within the relevant project for some of the key words in your issue. Or, if you can identify the relevant component (e.g. "Attachments", or "WYSIWYG editor"), try drilling down on the issues found there.

If you find that someone else has already filed a very similar issue, vote for the existing issue instead of creating a new one. You can also add a comment to the issue, if you have some information that would help us resolve it faster or can describe the issue in more detail.

Don't reopen issues that have been resolved and shipped

Please don't reopen resolved/closed issues once they have been shipped. If an issue similar to yours is marked as resolved, but you're still experiencing a problem with it, please create a new issue and provide a link to the original one. In the case of resolved bug-fix-issues, this will help us evaluate whether it is in fact the same problem, or actually a new issue with some of the same symptoms. In the case of resolved feature-issues, it is better to raise a bug-issue and link back to the feature-issue, and let us decide if we really want to reopen the original feature-issue as well.

Choose the appropriate project

Each of our products has its own JIRA project. Please file your issue in the project that matches the product you are using.

Is it a Bug? Or a Feature Request?

When filing a new issue, you will need to select one of the following issue types: "Bug", "Improvement" or "New Feature". Sometimes it can be difficult to differentiate between these three concepts. After all, fixing a bug means improving the product, and adding a new feature is certainly an improvement too.

Bug

A problem which impairs or prevents the functions of the product. If the product behaves differently from what was expected, that is a bug. If something should happen, but doesn't, that is a bug too. Write the summary of a bug in the following format: "Function X produces error Y when doing Z", or "Function X does not produce result Y though doing Z". If you can't write a short sentence similar to these, you are most likely not reporting a bug.

Improvement

An enhancement to an existing feature. An existing feature or function of the product works as advertised, but you would expect more from it. For example, "Function X should work faster when doing Z", or "Function X needs to do Y in order to make working with Confluence more efficient".

New Feature

A new feature of the product. This is a request for adding significantly new portions of functionality to the product. Write the summary like this: "Add function X to page Y", or "Create new feature X to enable Y".

Pick a good summary

When we're looking through lists of lots of issues, the summaries are essential in helping us to understand what an issue is about. This means that you should err in favour of putting too much information in the summary, rather than too little. Some examples:

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

Write a detailed description

When filing a Bug

There's a very simple, universal formula for bug reports. Every bug report must include:

1. Detailed steps to reproduce
2. What you expected to happen
3. What happened instead

The steps to reproduce should be written in terms that a monkey could follow: "Create a new Confluence page called 'Test'. Insert the following text: 'bq. I like cheese'. Set page permissions to 'Me'. Click the 'Save' button."

When filing an Improvement or New Feature request

Detail, detail, detail, context, context, context.

Tell us why you want the feature, as well as what it is. If the request comes from an email or IM exchange between co-workers, consider pasting that into the issue too!

Knowing why 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 a better solution than they'd even thought of, or we can aggregate a bunch of related requests into an über-solution that makes everyone happy.

Always choose a component

Every JIRA issue can be placed in one or more components. Most issues belong to one or two components; more than three should be avoided. The component is the second most important part of the issue after the summary, in terms of helping us quickly understand what the issue is about. 

If you can't find an appropriate component for your issue, please pick the closest one that almost matches.

Set the "Affects version"

When reporting a bug, please select the version of the product you were using where you encountered the bug. This helps us track down the bug, and it also helps us identify who else might be affected by it.

If you are using version 2.3 of a product, please select just 2.3 (not 1.8, 1.9, 2.0, 2.1, 2.2 and 2.3). If you know and want to point out that a bug already existed in 1.8, and still occurs in version 2.3, then please select 1.8 and 2.3, but not all the others in between.

Don't set the "Fix version"

Please do not select a fix-version. We will schedule the issues as appropriate.

Use images

Often, especially when describing bugs, an image will help tremendously to explain the issue. Once your new issue has been saved, you can easily attach a screenshot in just a few seconds — you don't have to save your image as a file and then upload it. 

Link issues

If you know that a feature request is similar (but not identical) to an existing one, please link it using a link type of "relates to". Or if a bug seems to be related to another one, please link them as well, even if you are not 100% certain. This will help us when we start working on your issue because we get a broader view of the problem, and may be able to solve not only one but two issues. And if the links turn out to be irrelevant, we will just remove them — no worries.

Set the priority

We have five priority levels. You can set an initial priority on the basis of how the bug affects you. Please use this list as a reference

  • Blocker: Server crashes and deadlocks for major configurations, users can't work properly. Examples of blocker bugs:
    • "After changing the default Confluence default language, no users can log in to Confluence anymore"
    • "The server deadlocks when more than 500 users log in"
  • Critical: Crashes, loss of data, severe memory leaks. Examples of critical bugs:
    • "After saving an edited page, all pages created by that user get erased"
    • "After a user changes his email address, his profile gets erased"
  • Major: Major loss of function. Examples of major bugs
    • "Users can't add labels to pages that have been labelled by other users already"
    • "When exporting a page to a PDF file most images are broken"
  • Minor: Minor loss of function, general annoyance, or other problem where easy workaround is present. Examples of minor bugs:
    • "Adding an image while editing a page does not work for french users, but images can always be added when going through the attachments page"
    • "When switching between rich text editor and plain wiki markup editor, unnecessary blank lines get inserted"
  • Trivial: Cosmetic problem like misspelled words or misaligned text. Examples of trivial bugs:
    • "The German translation of 'label' is incorrect"
    • "Typo in attachments page"

We may increase or decrease an issue's priority in accordance with the relative priorities of other issues.

Security issues

If you find a security bug in our products, open an issue on http://jira.atlassian.com in the relevant project.

  • Set the priority of the bug to "Blocker"
  • Provide as much information on reproducing the bug as possible
  • Set the security level of the bug to "Developer and Reporters only"

All communication about the vulnerability should be performed through JIRA, so we can keep track of the issue and get a patch out as soon as possible.