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.
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.
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.
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 )