JIRA Conventions

The available fields

JIRA issues each contain the following data fields:

There is also a "Status" field which is set implicitly as the issues is transitioned through the JIRA workflow.

New issues

Any TC member may enter a new JIRA issue to track a defect, a feature proposal, a task, etc. Additionally, comments entered to the public comment list, and those received via SC34 defect reports, will be transcribed into JIRA as new issues. A newly-entered issue will start in the "New" state. The author of the issue is automatically assigned as the "Reporter" of the issue. The author should enter as much detail on the issue as they have, in particular, an assignment to a "Component", a "Description" of the issue and "Proposal" for how to fix it. If the issue pertains to a specific version of ODF (and it usually does) then the author should also indicate that in the "Affects Version/s" field.

The author can also assign an owner of the issue in the "Assignee" field, if it has a clear owner. For example, editorial issue can be assigned to Patrick Durusau directly. Similarly, schema errors can be assigned to Michael Brauer, OpenFormula to David Wheeler and ODF-Next to Bob Jolliffe.

An issue in the "New" state can transition to one of two other states. If the issue entered is found to be a duplicate, or has already been fixed, or is superseded by another fix, or is incorrect or for whatever other reason cannot be acted on, then it can be moved directly to the "Close" state. If, however, the issue required further investigation or action, then it can be transitioned to the "Open" state.

Open issues

An issue is "Open" when it is being worked on. It does not mean that the issue will be fixed in any particular version of ODF. It does not mean that the issue is really a legitimate issue. It just means that the issue is being investigated or worked on. A recommended practice is this: If you have a "New" issue assigned to you and you can immediately determine that it is not a valid issue, then Close it directly. But if it requires more research, such that you will come back to it at another session, then mark it as "Open" so others know that you are working on it. Since "Open" does imply active work on the issue, all "Open" issues should have the "Assignee" field set.

An Open issue, once resolved, for whatever reason, should be transitioned to "Resolved".

Resolved issues

An issue is "Resolved" when there is nothing but editorial work remaining to fix it. This means that the "Proposal" field contains the technical resolution of any remaining technical questions. This does not mean, in most cases, that the exact final language has been proposed. But it does mean that any final wordsmithing may be done at the editor's discretion.

Since Resolved issues require only editorial work, they should all be assigned to an editor at the time they are transitioned to the "Resolved" state.

Once an issue is marked "Resolved" it is then transitioned to the "Applied" state via the "Apply Issue Resolution" action.

Applied issues

An issue is moved to the "Applied" state when the editor has amended his working draft to include changes necessary to implement the proposed resolution of the issue. This does not mean that the TC has approved these changes. Such approval will come with the approval of the draft text, as a WD or CD or whatever.

Once the draft is approved, say by a vote to adopt a CD, then all Applied issues with fixes contained in that draft may be marked as Closed.

Retrograde actions

JIRA also allows issues to move "backwards" through the process. For example, a "Closed" issue can be reopened". An Applied issue can see its fixes rejected and reopened for more work. And so on. These actions signal a disagreement between TC members and should be undertaken with caution and after consultation. It will often be appropriate to first discuss such state changes on the list or in a meeting.

More Information

- JIRA Introduction mail from Mary McRae, includes a basic description of the workflow and states.

JIRA_Conventions (last edited 2009-08-12 18:04:28 by localhost)