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 firstname.lastname@example.org.
- 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).
- People who want to submit issues, after creating their account, should review the Workflow.
- If you have questions regarding this tracking software (Jira), please send them to email@example.com.
- For Developers: Maintenance Branch Guidelines | Feature Branches | Jira Branches
- Sakai Community Servers are accessed from here (you'll test on them before creating a community Jira: http://nightly2.sakaiproject.org/ ).
- A user (anyone) Anyone with a JIRA account creates an Issue (please see #Create Issue Detailed Instructions first)
- Issue is automatically assigned to a Awaiting Review status
- 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.
- Once Open, developers ideally pick up the work and assign themselves to it as "Assignee." When they begin work, they selects Start Progress 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
- The Assignee sets the issue to Resolved with the relevant #Resolution when work is completed
- For tasks, if there is nothing explicit for the QA team to test, then the issue is Closed without testing.
- The QA team (potentially you!) selects Start QA 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
- 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)
- 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!
- 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)
- User searches You might also check the sakai mailing lists archives (nabble sakai lists archives).
- Searching nabble sakai-dev archives may help if you get too many results
- 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
- 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.
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.
(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:
Basic Definition for Sakai
|Impact on previous releases||Examples|
Release will not be completed until issue is resolved.
|Backported at least 2 major version (if applicable/affects). Potentially more than 2.|
Issue will most likely be resolved for release.
|Backported 1 major version back. 2 if applicable/affects and if no code conflict.|
Issue should be resolved for release.
|Backported 1 major version back if no code conflict|
Minor (Previously also Trivial)
Issue may be resolved for release.
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 closed out anything older than 2015.
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.