powered by Jive Software

Guidelines for using Jira

Introduction

This document will provide a set of guidelines for the usage of Jira in the Igniterealtime community. This is meant to guide all members of our community in the usage of Jira, including Project leads, committers and users alike.

Entering new tasks

  • When entering new tasks, leave them assigned to the default of Automatic. This will then be assigned to the project lead.
    • The exception to this is when the reporter is a contributor who will start work on the task in the very near future and thus they can assign it to themselves.
    • This exception does not apply to parent tasks. These are organizational, not actionable, so leave them assigned to the project leads.
  • Write a title that summarizes the problem or symptoms.
    • It should be clear enough to understand the basic problem/issue.
    • Do not propose fixes in the title, that can be done in the description or comments.
  • Always write a description. I know you think the subject line is beautiful in its simple clarity, but the opinions of others is likely to differ. This can include things like:
    • Actual details of the problem.
    • Stacktraces, if you have one, include it. They are invaluable sources of information.
    • Details of where the problem is or where you think it might be.
    • Potential fixes. Please be careful in suggesting the potential fixes, as they can easily cause just as many (or more) problems then solutions if they are wrong. Wild goose chases are not fun.
  • Include a link to the forums in the assigned text box if appropriate.
  • Parent/Sub tasks
    • Use a parent task to define a large tasks that can be broken up into several parts. It is meant to define and organize a large task, but is not in itself a work item.
    • Sub tasks are grouped under the parent. These define the individual tasks to accomplish the parent.
  • Link related issues using the appropriate link type.
    • This will help debugging efforts when the assignee knows that the problem may have associated issues or repercussions.
    • It may also help group tasks as parts of a larger overall task (Parent/Sub-task).

Task Workflow

For the project leads

Review all new tasks as soon as possible (within a couple of days of entry) and update them.

  • Check validity and close if appropriate.
    • Duplicates
    • New features that don’t align with the projects future.
    • Bugs that are either irrelevant or won’t be fixed due to existing or future planned changes, really custom behaviour or simply violate the spec.
  • Check/Set Priority
  • Check/Set Components
  • Check/Set Versions
  • Set assignee to unassigned.
  • Check that the description is adequate.
  • Periodically review tasks.
    • Tasks that are Assigned or In Progress that have not had any activity (change in status or commits) should be put back to Unassigned.
    • Check to see if older tasks are still valid.

For committers

Please note that all of the following instructions only apply to actionable tasks, that is, tasks that do not have a parent. Parent tasks are not to be assigned, marked as in progress or have code committed against them. Parent tasks are purely informational and organizational. They will be resolved by the project lead when all of the sub tasks are completed.

Current Status
Action
Unassigned

  • Assign it to yourself and get busy.
    Assigned
  • If it has been recently assigned, then give the assignee a chance. If you have information that you think is relevant, more details about the task, ideas for fixing it or a point you want to make sure are not forgotten, then by all means leave a comment.
  • If it has been assigned for a while and you would like to take the task, then contact the assignee and see if they are willing to have it reassigned. If you cannot get any response, contact the project lead.
    In Progress
  • It is the responsibility of all developers to set their tasks to this state when they are actively working on them.
  • Feel free to add comments to these tasks.
    Resolved
  • It is the responsibility of the developer to mark their task to this state when they are finished.
  • SVN comments MUST include the Jira task id so the code can be linked to the task. This allows for easy review of the code.
  • If you believe it is still not fixed, then reopen it. Add a comment as to why you believe this.
  • If you think the solution can be improved, then add a comment with your ideas and contact the project lead.
    Closed
  • Only the project lead sets tasks to this state.
  • Resolved tasks should be set to this state after the release has been completed. We assume the fix has been confirmed by this point.
  • Should only be rare to have to change the status here. If there are related issues they will probably require a new task to be created. It is still possible to reopen at the discretion of the project lead.

Comments

  • Comments are not for chatting or discussions. We have forums which are much better suited for that.
  • Comments should added value to the issue (the following is not a definitive list, just some examples).
    • fix suggestions
    • improvements on an applied fix or included patch
    • additional information about the issue (additional requirements, more debugging info …)
  • No “me too’s” (See previous point)
  • Comments that are deemed inappropriate may be deleted, this will be handled on a case by case basis.
2 Likes

On the spot and totally ok for me. As an addition (but that’s for project leads), I would like to point out that assigned task will be moved to unassigned, if there has been no visible work for a couple of months. Project leads may consider to use versions to combine unassigned taks into clusters of special interest. E.g. the Java 7 task may be unassigned and grouped.

Overall the project leads may work want to limit versioning to only one version (that is really managed and work upon) and a backlog.

Excellent. My comment would be, maybe one should also Link new ticket to another if one thinks they may be related (this will help project lead to combine them into a group or eliminate duplicates).

About Closing and Resolving. Sometimes i find long standing tickets (usually with Spark) that are no longer valid and you can’t tell when exactly they were fixed. Usually i close them and don’t assign latest version as a fix as it would be a misinformation.

The subject line/title is one of the most important things in every bug tracker/ticket system. Always state the sympthon, only state a proposed solution if it’s verified and you are sure that it will work and doesn’t break other things. OF-654 is a good example where a flawed solution was used as issue title, instead of the sympthon. This could lead to prematurly harmful actions. The issue tracker exists often also to work out an acceptable solution, but in first place it’s there to track issues. Therefore start with the sympthon/issue when entering a issue, then name possible solutions. Be precise in the subject line, put all the relevant information in the subject. Ideally one is able to recognize and get an idea of the issue just by reading the subject.

Don’t chat in the issue comments. Only comment if you think you have valuable information about the issue. I personally prefer a strict delete ‘me too’/‘when is this going to happen’ comment policy. Users are encouraged to vote for issues, watch them or ask in the community forums about the current states. Everyone who uses google code knows how painfull ‘me too’ comments are, when there is the execelty ‘star if’ feature. I hate comment cluttered issues. They make it hard to spot the important pices of information.

It’s great that we allow users to comment oo every issue, we should definelty keep that. But that also means that we need to moderate their comments and tell them about that policy.

Could we add these two points to the guidelines?

For the ‘assign issues to project lead’, see my comment here.

Yes, i think it should be clarified in these guidelines what should go into title. Solution or Symptom. This never was consistent, so i ofren wonder how to put it Though i also try to imagine how would it look in the changelog. Maybe it is more… encouraging to see that something has been fixed than a list of problems, which are supposedly fixed as they are listed in the Bugs section.

As about spam comments. It is not happening very often, but especially new users don’t comment on the forums (especially if there is no forums post linked), but register Jira account just to comment or bump the issue as many people think that issue tracker is the primaty tool to discuss issues (we often get complaints that our bug tracker is closed for outsiders). We can apply the policy, but how exactly? Should i just delete such comment without answering. Or comment that such comments are not permitted and then delete both comments? I hate when i have to keep in mind that i have to delete something at some point It is easier to bare such comments and not to start a war.

I would simply delete the comment and pm them with a link to the guidelines about using JIRA.

You mean to find if there is the same account in the forums and pm? Ideally it would exist, but sometimes it has different name, or as i mentioned some just skip the forums and only register with JIRA.

I like this idea. We use it at work for a major rework that will appear in some future but yet undefined release.

We also have two ‘versions’ called Product Backlog and Technical Backlog, basically pushing all tasks into one of these pseudo versions. Product Backlog is used for any task related to actual functionality and Technical Backlog is for technical improvements and upgrades, like the move to Java 7 example.

I will leave this as a suggestion for feedback.

Deleting something in the issue management sounds to me like the Dark Side of the Force. Unless it’s personal, I would leave it in there. But that’s just my take.

Why abuse the version field with pseudo versions if JIRA also has a label feature which is far more suitable?

Oh and it seems that discussing things on document with the comment field is pretty bad because there are no threads. I think it will get pretty confusing with more and more replies. I would create a thread somewhere and discuss it there.

I have added all the non-contentious points that have been raised.

I think when it comes to deleting comments, we should simply handle it on a case by case basis and we can be more aggressive with handling of violations of the guidelines if it seems to become an actual problem. Since we do restrict Jira access anyway, I don’t think there are any actual problems in this regard. Hopefully pointing out the proper procedure to someone will be enough.

As for the special versions, I won’t bother with my backlog suggestions, but Walter’s suggestion for grouped work makes sense and I have worked on teams that use this approach for major tasks or refactoring. Labels do not server the same purpose in this regard. What we are referring to is a group of related tasks that will all be included in the same future version, but we simply don’t know which one yet. This would only be used for tasks that are expected to take a long while to complete and would be worked on in their own branch. When work is complete or near completion it would have its version updated to the actual release version it is expected to be included in.

I agree about the comments here, it doesn’t flow very well (no pun intended Flow )