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: Maintenance Branch Guidelines | Feature Branches | Jira Branches


Basic Workflow

  1. A user (anyone) creates an Issue (please see #Create Issue Detailed Instructionsfirst)
  2. CLE team member verifies the issue for accuracy (i.e. is it an actual issue) and completeness of details.
  3. Assignee selects Start Progressand begins to work on the issue (as time and priorities allow)
  4. Assignee sets the issue to Resolved with the relevant #Resolutionwhen work is completed
  5. QA team selects Start QAand begins verifying the issue
  6. QA team verifies resolution of the issue and adds a comment with details of the testing results and process.
  7. Release Manager merges the issue (if it is a bug) to previous supported and affected releases 


(Exported from JIRA Sakai CLE Workflow on 31 March 2012 - AZ)


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.


Issue Type

Issue Type

Definition for Sakai


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


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.

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!]


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.



Definition for Sakai

Awaiting Review

Issue is waiting for investigation.


Issue is valid and ready to be worked on.

In Progress

Issue is actively being worked on.


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


Issue has been addressed and is ready for QA testing.


Issue has been tested and has passed. Ready for merging.


Work on issue is complete, no other activity.



Definition for Sakai


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


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.


Issue turned out not to be a problem with Sakai.


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.


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.


Not enough information has been provided to identify the issue.

Cannot Reproduce

Issue cannot be reproduced and more details or steps need to be added before it can be reopened.

No ResourcesIssue has no patch provided and there is nobody available to fix the issue at this time.

Branch Merge Status

Each branch has it's own status of the fix for it's branch. The field labels look like 2.9.x Status, 2.8.x Status, etc. These statuses do not tie directly into the overall ticket status and only the Branch manager should update this status.

ResolutionDefinition for Sakai
NoneNo merge needed for this ticket (i.e. only should be applied to
trunk or whereever it was committed)
MergeThe code changes related to this ticket should be merged into
the x branch.
ResolvedThe code changes have been merged
Closed<needs definition. perhaps a superfluous status?>
Won't Fix

Means the merge to the branch cannot be done and will not
be done (usually a reason is given in the comments - this is super


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.


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.


Definition for Sakai


Release will not be completed until issue is resolved. An example would be a severe problem that bridges multiple tools, or prevents core functionality in one tool.


Issue will most likely be resolved for release.


Issue should be resolved for release.


Issue may be resolved for release.


Issues that might be resolved before a release.



Security Level

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: