Summary and description
It is very important that the summary is short enough, and at the same time precise and long enough to convey all necessary information. Keep in mind that the summary is what appears in the change log, so it has to be clear enough. If anyone looking at the change log has to go to each issue's details to understand what changed and why, we missed our goal.
The sum of the summary and the description should tell
- what is being changed, added, removed
- why (with a typical use-case)
When resolving an issue, it's always nice to leave a little comment telling what has changed where. Revision numbers are superfluous since jira is linked to svn, but specifying this has been applied to the trunk and/or to certain branch(es) is nice; if we're talking about a technical change, a 3-word sentence saying what class was impacted is also good.
Use the "in progress" state
If you start looking into an issue, even if no concrete work is involved, mark the issue as "in progress". This will help, when approaching release time, knowing what we can bump to the next version or what we should finish. In progress issues are saying "hey, we've started something here, please double-check me before bumping or releasing".
Leave the issue "in progress" even if you're not touching it for days or weeks. Someone might take over. If part of the issue is solved, you might want to consider splitting it into several issues: resolve the current one and bump the (linked) one to the next release, for example.
Link issues
Use and abuse the issue linking feature of Jira. Add links even if you refer to another issue in a comment. Use the appropriate relationship descriptor.
Having the links help quickly checking what's left to do, what should be done before fixing an issue, etc. Anyone who wants to know more about a certain issue can check the links without having to do a search and thus get a broader view of the problem at hand.
Usage of labels
... todo.
Semantics of statuses
- Resolve: concrete work was involved and the issue is not an issue anymore.
- Close: issues are closed in 2 cases:
- the resolution was "accepted" (by the original request, by a reviewer, by the team) and closing the issues states this. We don't usually do this.
- the issue is "invalid". We typically do this for "won't fix", "not an issue" and "duplicate" issues. In these cases, no concrete work (code) was involved.
The resolution value is also very important, and one needs to pay attention that the combination of the status (resolved, closed) and resolution (fixed, won't fix, outdated
Possible improvements
Started this page as a placeholder for listing problems with and things we could do to improve our usage of Jira. Just rough ideas to be thought about, filtered, and maybe applied one day.
- how to know which issues haven't been treated yet
- using the Bucket plugin
- allowing unassigned issues (so assigning to yourself or someone would clearly mean this is being taken in charge)
- having a "reviewed by dev" flag
- systematically commenting on new issues when reviewed. that was we only need to regularly process issues where last participant is not a dev.
- having an "idea" or "todo" issue type (to avoid many of the "we should maybe do..." issues which are being forgotten
