Sakai JIRA Guidelines

Sakai uses Atlassian's Jira software for issue management. It is used to track a variety of issues, including bug reports, suggestions for new functionality, tasked work, and community contributions. Outlined below are the general practices, procedures, and definitions adopted by the Sakai community for using Jira.

Related pages:

General Workflow

  1. Anyone may Create an Issue (see #Create Issue Detailed Instructions)
  2. Assignee will Review issue is for accuracy and completeness of information.
  3. Assignee selects Start Progress and begins to work on the issue
  4. Assignee selects Resolve Issue with relevant #Resolution when work is completed, and updates Fix Version to the next major release version
  5. QA team verifies resolution of issue and adds a comment with details of the testing.
  6. Release Manager merges the issue to previous supported and affected releases

Create Issue Detailed Instructions

The Sakai community is encouraged to report issues and post feature requests in Jira, however, it should not consider as a primary destination for users of their own instance of Sakai to report issues. Rather, each organization running Sakai is expected to provide its own front-line support.

  1. User searches JIRA to see if the issue already exists (Sakai Jira Search)
  2. User searches the sakai mailing lists archives (nabble sakai lists archives)
  3. If user is not sure if the problem is a bug, they send a note to the sakai-dev mailing list first to ask
  4. User creates an issue in Jira of the appropriate #Issue Type

For all issues, please provide a simple Summary and Description that can be understood by all in the community, not just yourself or other developers. If you need to include some techno-babble, in addition to the plain language, for other developer types to understand the full details that's fine, but consider placing it in a comment on the issue.

If you need to include a large piece of information in an issue, such as a stack trace, please do not put it in the Description field. Instead, add it as an attachment or a comment. (This makes it a lot easier to view and parse issues in most browsers.)

Sometimes you may uncover bugs in your own code and need to create a Bug issue. If you think the bug does not affect past versions of Sakai and only exists in the code you are actively working on in trunk, then use the tentative release version that trunk will become as the Affects Version (_e.g._, 2.6 \[Tentative\]). Or, if you're working in a Jira branch, then use "branch" as the Affects Version.

JIRA Notifications

Whenever a Jira issue is modified, the issue's Reporter, Assignee, and any Watchers will receive an email notifying them of the change. To become a Watcher on an issue, go to the issue and view it, and click on the "Watch It" link. Additional notification options include:

Definitions

Issue Type

Issue Type

Definition for Sakai

Bug

An error in design or implementation which directly impedes a user from achieving their expected result.

Task

A new capability being added to Sakai.

Feature Request

A desired capability, for inclusion in a future release of Sakai; ideas that come with resources interested in implementing them are more likely to be developed than those offered with the hope that someone else will step forward to do the work.

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="b0c87d82-0838-4173-869b-69fc8e4aeb26"><ac:plain-text-body><![CDATA[

Contributed Patch

A community-contributed patch to a particular version of Sakai. The origin of such issues may lie in Bugs or Feature Requests which Sakai has not yet evaluated for implementation. Under such circumstances a linked issue is generally created by cloning the original issue in order to track Sakai's work on the issue. [Use at your own risk!]

]]></ac:plain-text-body></ac:structured-macro>

Branch

An experimental branch of code, which may or may not be merged back into the main code after the experiment completes; identified in SVN by a branch named with the Jira Key.

Status

Status

Definition for Sakai

Open

Issue is under consideration and investigation.

In Progress

Issue is actively being worked on.

Reopened

Issue was thought to be resolved, however, it did not pass QA and needs further work.

Resolved

Issue has been addressed and is ready for QA testing.

Closed

Work on issue is complete and has passed testing.
NOTE: Issue may still need to be merged into related branches.

Resolution

Resolution

Definition for Sakai

Unresolved

Issue is under consideration and/or actively being worked on.

Fixed

Issue has been addressed through changes to the design or code. When viewing an issue, the "Subversion Commits" tab provides specific details regarding code changes.

Won't Fix

Issue will not be addressed because it does not match project goals.

Non-Issue

Issue turned out not to be a problem with Sakai.

Duplicate

Issue is a duplicate of a previously submitted issue. A link to the other issue is added so that progress on the issue can be easily accessed.

Incorporated

Issue has been incorporated into another issue. A link to the other issue is added so that progress on the issue can be easily accessed.

Incomplete

Not enough information has been provided to identify the issue.

Cannot Reproduce

Issue cannot be reproduced.

Version

Each Jira issue has an Affects Version and a Fix Version. Generally speaking Sakai uses these values to indicate:

Further notes on Version Numbers

Maintenance Branch Version Numbers

A ".x" version is used to track issues relating to maintenance branches. For instance, 2.5.x is the version number representing the 2.5 release's maintenance branch.

If someone is basing their deployment on a maintenance branch, then there is the potential for confusion when using it as Affects Version, since the maintenance branch is a moving target. When reporting issues, it is important to indicate the revision number in the issue, so that folks know to which revision of the maintenance branch you are reporting the issue against. Even better is to determine if the issue affects the last maintenance release, and, if it does, use that as the Affects Version instead.

Priority

The Priority field in Jira is used by Sakai to reflect a combination of issue characteristics, including:

In practice, the Jira Priority field is utilized by Sakai at two times: during prioritization of feature requests/branches/contributed patches for implementation or merging, and when making decisions on what will actually appear in a release. Initial priorities, when an issue is first reported, may be changed to reflect needs as a release moves forward and priorities evolve.

As a release date approaches, priorities will also be adjusted - and lowered, if necessary - to reflect the decreasing availability of time and resources.

Priority

Definition for Sakai

Blocker

Release will not be completed until issue is resolved.

Critical

Issue will most likely be resolved for release.

Major

Issue should be resolved for release.

Minor

Issue may be resolved for release.

Trivial

Issues that might be resolved before a release.

Summary

Environment

Description

Component

Security Level