Anyway I decided to finally put the things that I nag my colleagues about into a set of hopefully useful basic tips for using JIRA effectively. I really am a JIRA obsessive at times…

TIP #1. When creating a new issue, think about the people interested in the issue.

JIRA almost exclusively uses the issue summary when displaying lists of issues, be they reports, portlets, Changelog or Roadmap. Therefore what you write in your Issue Summary is vital. It must be ubambiguous, clear and concise. Here are some real world summaries for issues I’ve been assigned, which do not meet the above criteria:

"Home page - title"
"Documentation"
"punctuation in a search term"

The only rational response to those is "Yeah, what about it?!" until you dig into the issue to view the description. See how they look in a dummy changelog scenario:

Release Notes - PROJECT XXX - Version 1.0

** Bug

    * [XXX-1] - punctuation in a search term

** Improvement

    * [XXX-2] - Home page - title

** Task

    * [XXX-3] - Documentation

Not exactly informative is it? Users/stakeholders will not really understand what has changed in this version.

Issue summaries should be concrete statements of problems or tasks, such that the changes effected in the behaviour of the project resulting from them is pretty obvious to the reader. We might re-write the above issues as:

"Change home page title text"
"Create new developer documentation"
"Punctuation handled incorrectly in search terms"

Much better, and it all looks much more professional too, vital for any public-facing project.

One common reason for vague summaries is creation of high level "macro" issues by an individual who does not understand the underlying tasks required to resolve the issue, which leads us onto the next tip…

TIP #2. Raise high-level requirements as issues, and use sub-tasks to structure the action required

If you are lucky enough to have JIRA Enterprise, you have the fantastic sub-task feature. It is a great shame Atlassian do not offer this in all versions as I think it is pivotal to effective JIRA usage, and the price differential between Standard and Enterprise is far too much if you just want sub-tasks and not the other enterprise features.

Rant-over, here is a typical usage scenario - Manager wants a new feature "Make widgets support Foo".

As a standalone issue this is annoying for developers as they have to edit it to make it apply to the underlying tasks or create new issues and, very clumsily, link them in to the original with issue linking. Still the relationship between the issues is not very visible.

The solution is for the people assigned to the issue to create sub-tasks of the issue breaking it down into the "technical" details of the job at hand.  Everybody can then see the status of the high level task in terms of its underlying tasks. See this example of such an issue

What’s even smarter is that high level tasks and sub-tasks do not need to share fix-for versions… which means you can pencil in your major functionality for release 1.0 but fix portions of it and release them in point releases 0.5, 0.6 and so on and only in final 1.0 release is the entire high-level task complete.

Anyway we have a couple of gripes about this:

1. Exported iCAL files always include issues even if you set issue count to zero in the portlet. I wonder if there Is a param to add to limit number of issues in the iCAL feed?
2. For the calendar portlet to be useful in the context of a filter handling many projects, you are forced to truncate your project version names to only include the number. This is ok as you can put descriptive text in the Description field of a version… BUT when you see affects/fix-for version list boxes when creating an issue it doesn’t show the description so Joe Bloggs in management says to me "Marc - where have all my version names gone, I don’t know if this issue should be fix for 2.0.2, 2.0.3 or 2.0.5 because I can’t see the info relating to the version any more".

I suppose with the latter, we need a way to either have the version list boxes show description also (maybe via a little ajax/JS panel?), or some kind of config for the calendar plugin to tell it stop parsing the version name property when it meets a certain character. Neither is very nice.

The problem is that the calendar plugin is potentially useful for us to keep abreast of what we have to achieve in the month in terms of version releases, but to do that means making issue creating much more error prone and confusing for those people who can’t remember exactly what each version number relates to on our project roadmaps.

When this happens I have to use “Bulk change” in Jira’s issue navigator to locate the subset of issues that are going to be “bumped” and change their Fix-for version to the next version.

However sometimes we need a new version inbetween the current and next, to handle those “bumped” issues. i.e. version 1.0.14 was going to have X and Y in it, and 1.0.15 is going to have P and Q in it. After bailing out issues that can’t be fixed for 1.0.14 we really need 1.0.15 et al to be moved up a revision number (to become 1.0.16 containing P and Q and so on), and a new 1.0.15 created containing just the issues bailed out from 1.0.14.

Because Jira is not version-number aware currently, it cannot do this. It could currently offer a “Split version” option in the Version Management page, so you could instead of Releasing make it “Split” the version into resolved and unresolved issues, and prompt for a new version number to sit in between this and the next release. So we could enter “1.0.14b” for example.

It’s not perfect - auto version numbering would be much better - but it would do until that comes.

1. You need to be able to “Send this portlet” to another user, and have it send them the required filter also if it is not a global shared filter.
2. They really need email announcements when versions are released, and allow users to “watch” projects to receive these emails.
3. Users should be able to choose only the projects they are concerned with. For example on jira.codehaus.org there are loads of projects and as a “privileged” user there I can see all of them, but that sucks. True this could be done with permissions but that means 1 permission scheme per project, and even then I might work on only 5 projects today, but a couple more next week. The project pop ups are therefore extremely overloaded for me.