Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Sakai JIRA Guidelines

Table of Contents

Sakai uses Atlassian's Jira software for issue management. It is 's 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.

  • Users who want to submit issues should review the Workflow.
  • If you have questions regarding Jira, please send them to
  • You can search and view content in Jira without an account, but one is are required to have one to comment or create issues. Jira accounts are available through through self-registration (Jira and Confluence share accounts).



Basic Workflow

  1. A user (anyone) Anyone with a JIRA account creates an Issue (please see #Create Issue Detailed Instructionsfirst first)
    • Issue is automatically assigned to a Awaiting Review status
  2. A Sakai Core team member verifies , and/or anyone who wants to participate in "JIRA Triage" weekly calls, verifies the issue for accuracy (i.e. is it an actual issue) and completeness of details.
    • Complete and valid issues are set to status Open and assigned to a user or group (e.g. Samigo Team or Sakai Core Team) who can resolve it.
    • The team member may resolve the issue as Duplicate , Incomplete , or Cannot Reproduce if appropriate (see #Resolution).
    • It may also be set to Awaiting Information if it doesn't contain enough information to Open for work.
  3. Once Open, developers ideally pick up the work and assign themselves to it as "Assignee." When they begin work, they selects Start ProgressProgress and begins begin to work on the issue (as time and priorities allow)
    • The Assignee selects Stop Progress if they are not going to work on the issue anymore for a few days and it is not resolved
  4. The Assignee sets the issue to Resolved with the relevant #Resolutionwhen  when work is completed
    • For tasks, if there is nothing explicit for the QA team to test, then the issue is Closed without testing.
  5. The QA team (potentially you!) selects Start QAQA and begins verifying the issue
    • QA team member selects Stop QA if they are not going to complete the testing on the issue within a short time frame
  6. The QA team verifies resolution of the issue and adds a comment with details of the testing results and process.
    • If verification fails, then it is Reopened for further work (automatically re-assigned to the user who resolved it)
    • If verification succeeds then QA marks the status as Verified (indicating it has been Tested)
  7. The Release Manager merges the issue (if it is a bug) to previous supported and affected releases 
    • The associated version merge status is set to Resolved   (see  #MergeStatus )
    • The issue is Closed by the Release Manager when the last merge has been completed


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. The Community maintains a set of servers for testing. If you find an issue on your own institution's Sakai servers, please don't report that to the community. Rather, each organization running Sakai is expected to provide have its own front-line support.


issues list. However, should an issue on your institutions' Sakai be found, AND that issue also exists on one of the community's servers, it should be reported to the community. Here's how!

  1. You search JIRA to see if the issue already exists (Sakai Jira Search)
    • Search strategies include searching for a particular component, sorting by update date, and exporting as an MS Excel file (in Views)
  2. User searches You might also check the sakai mailing lists archives (nabble sakai lists archives).
  3. If user is you're not sure if the problem is a bug, they then send a note to the sakai-dev mailing list first to ask
  4. User creates You then create an issue in Jira of the appropriate #Issue Type
    • The component should be set based on where the problem appears to exist. Do not use the Performance component however. Use  Only use a 'Performance' label to flag performance related issues so there is a consistent way to filter these issues across projects.
    • The Assignee should be left as -Automatic-
    • The Affects Version should be set to the released version of the instance of Sakai being used.
    • The Fix Version should be left set to the default of Unknown. The project teams will set the Fix Version once they have had time to review the issue and estimate when they believe they will be able to address it.
    • As much of the following information should be included as possible (to avoid the issue being closed as incomplete)
      • Sakai version
      • (bugs) Steps to reproduce (detailed and step by step)
      • If disambiguation is necessary, include Expected Results and Actual Results
      • Environment details (DB type and version, tomcat version, OS type and version, Browser and version, etc.)
      • (bugs) URL to the page where the error occurs
      • (bugs) Stacktrace (traceback) if available
      • (bugs) relevant portions of the server logs (do not attach your entire logs, we do not have time to read through 1000s of lines of logs and figure out where the relevant parts are)
      • (bugs) Screenshots or Screencasts showing the error
      • (feature) Use cases and detailed requirements
      • The desired resolution

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


  • Affects Version - Version(s) in which an issue is observed, and should be a released version of Sakai. Do not use unreleased versions.
    • If you find an issue in trunk, and it is a problem that only affects trunk and not previous releases, then please use the next planned release as the Affects Version. If the issue also affects released versions of Sakai, then please include those versions too.
  • Fix Version - Version(s) for which an issue is anticipated to be fixed (for Unresolved issues) or in which it is the issue is actually fixed (for Resolved/Closed and Fixed issues). Leave blank for Unresolved issues.

Further notes on Version Numbers



 (Updated for Sakai 12, inspired by Drupal priorities)

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. Every issue comes in as Major priority and each Jira is triaged to determine the appropriate priority.

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

Issues that might be resolved before a release


Basic Definition for Sakai

Impact on previous releasesExamples


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.

Backported at least 2 major version (if applicable/affects). Potentially more than 2.
  • Render a site unusable and have no workaround.
  • Cause loss/corruption of stored data. (Lost user input, e.g. a failed form submission, is not the same thing as data loss and in most cases is major).
  • Expose serious security vulnerabilities.
  • Errors in grading calculations affecting most students/instructors.


Issue will most likely be resolved for release.

Backported 1 major version back. 2 if applicable/affects and if no code conflict.
  • Interfere with normal site visitors' use of the site (for example, content in the wrong language, or validation errors for regular form submissions), even if there is a workaround.
  • Trigger a Java error through the user interface, but only under rare circumstances or affecting only a small percentage of all users, even if there is a workaround.
  • Render one feature unusable with no workaround.


Issue should be resolved for release.

Backported 1 major version back if no code conflict
  • Admin- or developer-facing bugs with a workaround.
  • Bugs for site visitors that do not interfere with site use, for example, visual layout issues.

Minor (Previously also Trivial)

Issue may be resolved for release.

Image Removed Trivial

Not backported
  • Used for cosmetic issues that do not inhibit the functionality or main purpose of the project.



  • You can subscribe to filters in Jira and receive an email summary of the filter's contents at a time interval you specify. For those interested in a daily summary of updates in the Sakai project in Jira, you should subscribe to the "Updated in Last 24 Hours" filter, and specify a 24-hour or 1-day time interval. (Note that the time of day when you subscribe is the time of day when Jira will send the digest, so you probably want to subscribe to the filter early one morning.)
  • Jira can also send on-event notification emails, such as whenever an issue is created, updated, resolved, closed, etc. If you are interested in receiving such emails, then please contact

Jira Spring Cleaning
Jira Spring Cleaning
Jira Spring Cleaning

Every year we should resolve out old issues. I plan to do this by the end of each April as this is the time when we update servers and well it's Spring in some parts of the north. We default to closing out issues that haven't had any updates more than 3 years ago 3 years. So in 2018 we closed out anything older than 2015.

This is the JQL to search for these issues. Search for these
updatedDate < "2015/01/01" and project = sak and status in (Open,"Awaiting Review")

Then do a "Bulk Change"
Transition Issues

Select "Won't Fix" as a Resolution and add this comment (updating the date) :
Bulk closing issues that have not been updated since 2015 and earlier. Please reopen if this is still an issue and you have new information or if this is a feature you'd like to still have consideration for.