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

Summary

Basic Workflow

  1. Anyone with a JIRA account creates an Issue (please see #Create Issue Detailed Instructions first)
  2. A Sakai Core team member verifies the issue for accuracy (i.e. is it an actual issue) and completeness of details.
  3. The Assignee selects Start Progress and begins to work on the issue (as time and priorities allow)
  4. The Assignee sets the issue to Resolved with the relevant #Resolution when work is completed
  5. The QA team (potentially you!) selects Start QA and begins verifying the issue
  6. The QA team verifies resolution of the issue and adds a comment with details of the testing results and process.
  7. The Release Manager merges the issue (if it is a bug) to previous supported and affected releases 

Diagram

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

Details

Create Issue Detailed Instructions

The Sakai community is encouraged to report issues and post feature requests in Jira. The Community maintains a set of servers for testing. If you find an issue on your own institution's Sakai servers, please do not report that to the community. Rather, each organization running Sakai is expected to have its own 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)
  2. You might also check the sakai mailing lists archives (nabble sakai lists archives)
  3. If you're not sure if the problem is a bug, then send a note to the sakai-dev mailing list first to ask
  4. You then create 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 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 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.

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.

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

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

Awaiting Review

Issue is waiting for investigation.

Open

Issue is valid and ready to be worked on.

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.

Tested

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

Closed

Work on issue is complete, no other activity.

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

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

Priority

Basic Definition for Sakai

Impact on previous releasesExamples

Blocker

Release will not be completed until issue is resolved.

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.

Critical

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.

Major

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.

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

Environment

Description

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:

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'd close 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.