Versions Compared

Key

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

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.

...

titleJira Account
  • You can search and view content in Jira without an account*, however, you do need one to comment or create issues. Jira accounts are available through self-registration. (Note that Jira and Confluence share accounts, however, Jira/Confluence accounts are separate from Collab accounts.)

...

What happens when an issue is created in Jira? The workflow for a given issue is dependent on what type of issue it is. The sections below describe the overall path an issue of given type will follow. Guidelines are also presented for the various groups interacting with issues, such as Designers, Developers and QA, and discuss when and how to adjust an issue's status, resolution, versions, etc.Related pages:

General Workflow

  1. Anyone may Create an Issue (see #Community #Create Issue Detailed Instructions)
  2. Assignee will Review issue is for accuracy and completeness of information.
    • The issue maybe resolved as Duplicate, Incomplete, or Cannot Reproduce if appropriate (see #Resolution). All issues resolved with a resolution other than "Fixed" should not have a Fix Versions set, (they were not fixed!) Their Fix Version should be "Unknown".
    • The issue may be linked to other related issues.
    • The issue may be assigned to someone else in a better position to review and/or resolve.
    • The Priority may be adjusted
    • Other attributes may be changed as appropriate, such as Components, Affects Version, Security Level, Original Estimate, etc.
  3. Assignee selects Start Progress and begins to work on the issue
    • If you are implementing a Feature Request or Contributed Patch, first use Move to covert the issue type to a Task
    • If working in a branch, first merge your branch to trunk before resolving the issue
  4. Assignee selects Resolve Issue with relevant #Resolution when work is completed, and updates Fix Version to the next major release version
    • Assignee edits the issue and adds a Test Plan under "Testing"
    • Assignee edits the issue and adds relevant "Release Notes"
    • Assignee edits the issue and selects Merge for previous supported and affected releases (e.g. 2.8 Status)
    • For Tasks, if there is nothing explicit for the QA team to test, then please Close the issue.
  5. QA team verifies resolution of issue and adds a comment with details of the testing.
    • If it fails verification, then it is Reopened and re-assigned for further work, and the Affects Version is updated to include the version tested.
  6. Release Manager merges the issue to previous supported and affected releases
    • The associated merge status is set to Resolved
    • The issue is Closed when all merges to previous releases have been completed

...

  • Important to create a detailed description on how to recreate the bug

...

  • Tasks are used by project teams to track the addition of or changes to functionality.
  • When the task is completed, the Assignee Resolves it as Fixed, as above with Bugs.
  • It is not necessary to set an Affects Version for a Task.
  • When a Task is created, and is in an Unresolved state, its Fix Version should indicate for which version of Sakai an issue will be addressed.
  • When a Task is Resolved/Closed and Fix, then its Fix Version should indicate in what version of Sakai it was addressed.
  • Assignee should edit the issue and add a Test Plan under "Testing" and also adds relevant "Release Notes"

...

  • Issue is vetted for accuracy and completeness of information.
  • The issue is evaluated by the appropriate project team, just like a Feature Request or Branch, for inclusion in a future release of Sakai.
    • In some cases, a Contributed Patch may run counter to the Sakai design and cannot be incorporated, and maybe marked as Won't Fix and an explanation as to why provided. In this case, the contributor of the Patch may choose to continue developing the patch for future versions of Sakai.
  • Until the patch is integrated in Sakai, the community encourages the contributor to be responsive to comments and feedback provided by other users of the patch and to continue to update the patch to current versions of Sakai
  • Assignee should edit the issue and add a Test Plan under "Testing" and also adds relevant "Release Notes"

...

  1. Issue is vetted for accuracy, completeness of information, relevance to Sakai's overall design, etc.
    • A good Feature Request should explain clearly what a user is trying to achieve. Use cases and scenarios can be helpful in communicating that.
  2. Assigned to appropriate Project Team or Working Group lead, The will evaluate and discuss such issues periodically, when the group reaches an appropriate point in the release cycle to adsorb community input.
    • If the decision is made to not address the issue, then it should be resolved as "Won't Fix" with appropriate comments.
  3. When a project team is ready to address the issue, it should be Moved to a Task and an initial estimate of the Fix Version set.

General Workflow by Role

...

    • In the process of verifying the issue, if you discover a different problem, create a new issue to capture it, rather than re-opening the current issue and re-using it; reserve re-opening only if the original problem is still present.
    • Some issues can not be easily verified and may require special testing conditions or input from developers.
    • Close the issue. This will move the issue from the "Awaiting Verification" to the "Verified" list in Jira.
  1. Release Manager merges the issue to previous supported and affected releases
    • The associated merge status is set to Resolved
    • The issue is Closed when all merges to previous releases have been completed

Anchor
Create Issue Detailed Instructions
Create Issue Detailed Instructions
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 (create issue) of the appropriate #Issue Type
    • The component should be set if it is known (leave blank if not sure)
    • The Assignee should be set as Unassigned (ideally) or left as -Automatic- (do NOT assign to a developer directly)
    • 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)
      • 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 showing the error
      • (feature) Use cases and detailed requirements
      • The desired resolution

...

Planning

As new issues come in and as you periodically review the status of existing issues, use the Fix Version to indicate for what version you expect to implement a solution for the issue. If you are unsure when you will be able to address the issue, then leave or set the Fix Version to Unknown.

Creating an Issue

Typically you will be creating Task issues to describe new features or functionality you are planning to implement. If the change is significant or experimental in nature, consider creating a Branch issue instead and doing the work in a Jira Branch. (See the Release Practice Guidelines for more details on Jira Branches.) You may also need to create Bug issues for problems you uncover and need to fix in your project.

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.

Also, please provide an initial estimate of when you plan to fix an issue by specifying an appropriate future release of Sakai as the Fix Version. Generally this will be the next major release of Sakai (e.g., 2.6).

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

Wiki Markup
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.

Working on an Issue

In most cases you will be working on an issue in trunk and should do the following (otherwise see exceptions):

  1. Assign the issue to yourself to work on.
  2. If you are implementing a Feature Request or Contributed Patch, first use Move to covert the issue type to a Task and set the Fix Version to reflect for which version you expect to complete your work (see #Planning above.)
  3. Work on the issue, updating, modifying, commenting, re-assigning, etc. as necessary to achieve resolution.
  4. Wiki Markup
    When work is complete, and if the resolution of the issue is *Fixed*, then *Resolve* the issue and *set the Fix Version to the next major release* (_e.g._, 2.6 \[Tentative\]). If the resolution is other than Fixed (_e.g._, Duplicate, Non-Issue, Cannot Reproduce, Incorporated), then set the Fix Version to Unknown.
    • For Tasks, if there is nothing explicit for the QA team to test, then please Close the issue.
    • For Bugs, just leave the issue as Resolved, and the QA team will Close it after verifying it, or Reopen it for further development if the original issue was not resolved.

...

Exceptions

Working in a branch?

  • Follow the same procedures as working in trunk, except use branch as the Fix Version.
  • When your branch is completed, follow the Jira or Experimental Branch procedures for merging your branch, and reset the Fix Version appropriately.

Working on a bug specific to a maintenance branch?

  • Follow the same procedures as working in trunk, except use the maintenance branch version (e.g., 2.4.x, 2.5.x) as the Fix Version.
  • You should also coordinate your work with the Branch Managers.

Working on a bug specific to trunk, in other words the next release?

  • Sometimes as trunk evolves bugs get introduced that do not affect a past release, only the current, evolving codebase in trunk.
  • Wiki Markup
    Use the next release (_e.g._, *2.6 \[Tentative\]*) as the *Affects Version*. (If the bug is not fixed before the next release is made, then the issue will end up correctly listed as a Known Issue without any further intervention.)
  • If you plan to fix the bug in time for the next release, you can use the same version again as the Fix Version. If you plan to fix it for a later release, enter that release's version as a tentative estimate for completion; otherwise, leave the field set to Unknown.
  • (Issues with equivalent Affects and Fix versions will not generally be reviewed by QA, as they are considered transient issues.)

Security Releases

As of Sakai 2.5. Security Releases are no longer being made. Instead, maintenance releases, which will include security fixes, will be provided. (Previously, security releases included only security fixes on top of the previous major release, but did not include any other fixes; such releases did not meet the needs of the community and are no longer provided.)

Maintenance Branches

See Maintenance Branch Guidelines.

Feature Branches

See Feature Branches.

...

Jira Branches

See Jira Branches.

...

Releases

  1. Select an appropriate issue from the list of issues "QA Awaiting Verification".
  2. Attempt to verify the issue.
    • In the process of verifying the issue, if you discover a different problem, create a new issue to capture it, rather than re-opening the current issue and re-using it; reserve re-opening only if the original problem is still present.
    • Some issues can not be easily verified and may require special testing conditions or input from developers.
  3. If the issue passes verification:
    • Verify the Fix Version is correct. Generally the Fix Version of an issue will be correctly set when it is merged into the branch, however, under certain circumstances, such as re-resolving re-opened issues, the Fix Version may need updating. Typically the Fix Version is the version of Sakai you've verified the fix in.
    • Close the issue. This will move the issue from the "Awaiting Verification" to the "Verified" list in Jira.
  4. If it fails verification:
    • Update Affects Version to include version tested.
    • Reopen issue and re-assign to the developer. If is not clear to whom the issue needs to be re-assigned, then assign it to default.

Maintenance Branches

See Maintenance Branch Guidelines.

Security Releases

To be filled in...

...

Maintenance Branch Manager

See Maintenance Branch Guidelines.

General Workflow by Task

...

Suggest Merge to Maintenance Branch

Set the appropriate maintenance branch "status" field to "Merge" for an issue to indicate that you would like to see it merged to a particular Maintenance Branch. Each Maintenance Branch has its own status field: 2.4.x Status, 2.5.x Status, etc.

...

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:

  • 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-admins@collab.sakaiproject.org.

Anchor
Definitions
Definitions
Definitions

...

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="9707efbec0f0f7b6-e4666359-4f2a4d3a-8f5da6ae-95a9f0a825cf63e60c3d8a5e"><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.

  • Image Added Bugs
    • Important to create a detailed description on how to recreate the bug
  • Image Added Tasks
    • Tasks are used by project teams to track the addition of or changes to functionality.
    • It is not necessary to set an Affects Version for a Task.
  • Anchor
    Contributed Patches
    Contributed Patches
    Image Added Contributed Patches
    • Issue is vetted for accuracy and completeness of information.
    • The issue is evaluated by the appropriate project team, just like a Feature Request or Branch, for inclusion in a future release of Sakai.
      • In some cases, a Contributed Patch may run counter to the Sakai design and cannot be incorporated, and maybe marked as Won't Fix and an explanation as to why provided. In this case, the contributor of the Patch may choose to continue developing the patch for future versions of Sakai.
    • Until the patch is integrated in Sakai, the community encourages the contributor to be responsive to comments and feedback provided by other users of the patch and to continue to update the patch to current versions of Sakai
  • Image Added Feature Requests
    • Issue is vetted for accuracy, completeness of information, relevance to Sakai's overall design, etc.
      • A good Feature Request should explain clearly what a user is trying to achieve. Use cases and scenarios can be helpful in communicating that.
    • Assigned to appropriate Project Team or Working Group lead, The will evaluate and discuss such issues periodically, when the group reaches an appropriate point in the release cycle to adsorb community input.
      • If the decision is made to not address the issue, then it should be resolved as "Won't Fix" with appropriate comments.
    • When a project team is ready to address the issue, it should be Moved to a Task and an initial estimate of the Fix Version set.

Anchor
Status
Status
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.

...

  • Controls the visibility of the issue; currently toggles between viewable by anyone or by just the committers and testers (and the reporter of the issue).

...

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.

There are also a couple of strategies for monitoring Jira issues en masse:

Email Summaries of Jira Filters

You can subscribe to filters in Jira and receive an email summary of the filter's contents at a time interval you specify.

For folks 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.)

On-Event Automated Notifications

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-admins@collab.sakaiproject.org.

...

  • Wiki Markup
    All issues resolved as "Fixed" should have a Fix Version set, which generally is the next major release version (_e.g._, "2.6 \[Tentative\]").
  • All issues resolved with a resolution other than "Fixed" should not have a Fix Versions set, (they were not fixed!) Their Fix Version should be "Unknown".