This post is intended as a living document that will evolve and grow over time. If there’s something you think I missed or would like something clarified, please feel free to leave a comment.

Who should be reading this FAQ?

Managers, developers, testers, anybody working or contributing on a software project.

This article is generally JIRA specific, however concepts will carry across into other issue trackers such as Bugzilla, Redmine, Team Foundation Server (TFS) and Trac just fine.

When should a small team be using an issue tracker such as JIRA?

A young startup may initially get away just fine by working informally and by email, and early in the project you’ll want to have as little administrative burden as possible, however as a project and team matures, there will come a time when having a searchable, persistent audit history of business decisions, fixes (and why they were done) and completed tasks will become invaluable.

This audit history goes hand-in-hand with a good version control commit history.

Can’t I just email the person?

Sometimes. However if you email the person details of the issue, and if the issue ends up in JIRA, make sure you add all the relevant details into a JIRA issue too; JIRA issues should be complete and not refer to emails.

If you’re copy+pasting from an email and intend to quote somebody, you can use the {quote} Text Effect

General guidelines for deciding on the Issue Type

I recommend creating a new issue type of Observation. In the context of creating an issue, an observation is something you noticed in the system and you’re not sure if it’s a bug or not.

Unless you know it’s a genuine bug, Observation is a good Issue Type default. The issue type can always be changed later after the issue has been reviewed.

Anything administration related is usually a Task, any non-bug refinements can usually be classified as Improvements, and any upcoming features can usually be classified as New Features.

What to do when two people need to work on different parts of an issue

When an issue can be separated cleanly into more than one unit of work, create one parent issue and then create sub tasks as more granular tasks which can then be assigned to individual users.

In the case where the work can’t be separated cleanly, or it’s not obvious how to separate the work into sub tasks, create an issue as you would normally and assign to the person who is likely to be the best to start the investigation.

More info:

What to do when you’re finished with an issue

After you’ve fixed the issue assigned to you, on the issue page click on the Resolve button, setting the resolution to Fixed and leave a comment describing in general what was done.

When the fix has been deployed, ensure the issue is marked as **Fixed **with an appropriate comment and assign it back to the user who initially created the issue.

If the issue won’t be fixed for whatever reason, leave a comment describing why, mark the issue as Won’t Fix and assign back to the user who initially created the issue. Similar for the resolution types of Cannot Reproduce and Incomplete.

What to do when an issue is no longer an issue

Then it should be closed. This is usually done by the creator of the issue or the test team.

Why are we doing all this administrative work instead of just working on the code?

Six months or more down the track when you’re looking at some part of the functionality and wondering why something was done or the system is behaving in a certain way which isn’t understood by anybody on the team, an audit trail will come in very handy.

An audit history is not a panacea however it will help immensely with the question of “why did we do that?”

There are several scenarios where this audit history will be highly valuable:

  • The most common scenario is when there has been a lot of code and business rule churn with changing requirements and shifting priorities, where some features may have partially implemented or pivoted part of the way through development.
  • When the people who wrote the initial code have left the project. You can’t necessarily ask them why something was done.
  • When people have simply forgotten!

As a side note, version control commits also represent an audit history of the changes at a more technical level and include a reference to the JIRA issue when appropriate.

In summary, the JIRA audit history should consist of a searchable history of approvals, business decisions, implementation details. It should answer all your questions of why something was done.