Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 137 Next »

Jira

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.

Jira Account

Jira and Confluence share user accounts. You do not need an account to view content in these systems, however, you do need one to comment on or post information. You can request an account from jira-admins@collab.sakaiproject.org.

Note that your Jira/Confluence account is completely separate from a Collab account, http://collab.sakaiproject.org, and a Sakai website account, http://www.sakaiproject.org; currently you need a separate username and password for each system.

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/Requirement

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="b6534432-f321-4c5f-bf3e-ffbd156e81cd"><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 orignal issue in order to track Sakai's work on the issue. [Use at your own risk!]

]]></ac:plain-text-body></ac:structured-macro>

Status

Status

Definition for Sakai

Open

Issue is under consideration.

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

Closed

Work on issue is complete and has passed testing.

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. Such an issue might become a Feature Request.

Non-Issue

Issue turned out not to be a problem with Sakai. Such an issue might result in a Feature Request or become an entry in the Sakaipedia if it is a common point of confusion.

Duplicate

Issue is a duplicate of a previously submitted issue. A link to the original 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. Perhaps it was a non-Sakai problem or it was resolved as a by-product of other work.

Version

Each Jira issue has an Affects Version and a Fix Version. Generally speaking Sakai uses these values to indicate:

  • Affects Version - Version in which an issue is observed. This should never be set to a "future" version of Sakai, e.g., Post-2.1.2; issues should only affect Sakai relative to a known existing version.
  • Fix Version - Version in which an issue is resolved. This could be a "future" version of Sakai, when indicating a future release you expect an issue to be resolved in.

Both of these versions, however, are not necessarily meaningful for all issue types. The table below summarizes how they are used in the context of specific issue types.

Issue Type

Affects Version

Fix Version

Bug

Version in which bug was identified.

Version in which bug is expected to be or has actually been resolved. (star)

Task

Not required, but may provide useful context for comments on the issue.

Version in which new capabilitity is expected to appear or has appeared. (star)

Feature Request

Not required, but may provide useful context for comments on the issue.

Not applicable. (Note that Feature Requests selected for implementation are currently converted to one or more Tasks for tracking the actual work.)

Contributed Patch

Version to which the patch can be applied.

Not applicable. (Note that Contributed Patches are cloned to provide a separate Bug or Feature Request for tracking Sakai work on the issue.)

(star) For both Bug and Task issues the fix version depends on whether the issues is unresolved ("expected" fix version) or resolved ("actual" fix version).

  • For unresolved issues, which are still being worked on, the fix version is set to the release number in which the issue is expected to be resolved. Generally, this is is the next version's first QA release, such as 2.3.0.001.
  • For resolved issues, developers should set the fix version to "Nightly/SVN-trunk", unless they know for sure what release the fix will be incorporated in. As perparations are made for each QA release, the fix version will be updated appropriately. (QA folks will also double-check the fix version at verifcation time to ensure that it is correctly set relative to the release they are testing.)

After a release is made, the interim QA release versions are merged into the "whole" version release number. For example, 2.2.1.001, 2.2.1.002, and 2.2.1.003, were the three QA releases for that version, and they were merged into 2.2.1. The merging is important in keeping it simple to search, filter, and view issues for released versions of Sakai.

Further notes on Version Numbers

When development work predominates on a branch – prior to a the branch entering QA – the version number to report issues against is basically a moving target. In other words, as fixes are checked into a branch, there is currently no change in the version used to refer to that branch; the SVN revision number, however, does change, so use that if you need to track that level of granuliarty. For instance, for issues encountered on the trunk branch, report the Affects Version as "Nightly/SVN-Trunk. When such issues are resolved prior to QA, the Fix Version is similarly set, which helps identify potentially transient issues that might not need full attention during QA.

Maintenance Branch Version Numbers

A ".x" version is used to track issues relating to maintenance branches. For instance, 2.2.x is the version number representing the post-2.2.2 release maintenance branch. This version number should only be used by the maintenance branch manager as a Fix Version. It is used to indicate that for a particular Jira the associated revisions have also been merged into the maintenance branch, in addition to trunk.

If someone is running the maintenance branch, then it may be used as an Affects Version, however, be forewarned of the potential for confusion since the maintenance branch is a moving target. In such a situation it is important to indidate the revision number in the Environment field, so that folks know to which version of the maintenance branch you are referrning.

Priority

The Priority field in Jira is used by Sakai to reflect a combination of issue characteristics, including:

  • Number of users affected
  • Resources required to resolve

In practice, the Jira Priority field is utlized by Sakai at two times: during prioritization of requirments for implementation 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 those needs.

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

Priority

Definition for Sakai

Blocker

Release will not be completed until issue is resolved.

Critical

Issue will most likely be resolved for release.

Major

Issue should be resolved for release.

Minor

Issue may be resolved for release.

Trivial

Issues that might be resolved before a release.

Summary

  • A brief statement summarizing the issue. (Field is limited to < 255 characters.)

Environment

  • A description of the Sakai enivronment in which the issues was encountered, e.g., web browser, operatings system on which Sakai is installed.
  • For QA participants this is a good place to note on which test server the issue occurred (e.g., MIT Stable HSQL, MIT Stable Oracle, MIT Stable MysQL, Nightly)

Description

  • A detailed description of the issue, including the steps necessary for reproducing the issue.
  • You can also add attachments, including screen shots to help illustrate the issue.

Component

  • The particular part or parts of Sakai related to the issue.

Security Level

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

General Workflow

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 variours groups interactig with issues, such as Designers, Developers and QA, and discuss when and how to adjust an issue's status, resolution, versions, etc.

General Workflow by Issue Types

Bugs

  1. Issue is Opened.
  2. Issue is vetted for accuracy and completeness of information and linked to related issues.
    • (Duplicate) If it duplicates a previous issue, then the newly opened issue is:
      1. Linked to the original issue as "duplicates"
      2. Commented with a note to look at the original issue to track progress
      3. Closed with a Resolution of "Duplicate"
    • (Non-Issue) If it turns out that the issue was the result of a mis-understanding of how Sakai operates, then:
      1. An effort is made to clarify the situation.
      2. If the mis-understanding does not suggest a design flaw, then it is Closed with a Resolution of "Non-issue"; otherwise, the design flaw could be captured to a Bug or Feature Request.
    • (Incomplete) If insufficient information is provided to describe the issue, then:
      1. An effort is made to obtain additional information.
      2. If insufficient information is provided in a reasonable time-frame, then the issue is closed with a Resolution of "Incomplete"; issue can always be Reopened.
    • (Cannot Reproduce) If the issue cannot be reproduced on one of the QA test servers, then:
      1. An effort is made to obatain additional information.
      2. If insufficient information is provided in a reasonable time-frame, then the issue is closed with a Resolution of "Cannot Reproduce"; issue can always be Reopened.
  3. Issue is assigned to the appropriate project lead.
    **Further vetting, as above, may be necessary for particularly complex issues.
  4. Initial estimates of the scope of the bug and the resources required to address it are made and the reported Priority and Fix Version are updated accordingly.
  5. An issue may be re-assigned to others or Watchers added to facilitate discussion of its resolution. The Priority, Fix Version, Components, etc. should also be updated as necessary as discussion around the issue evolves.
  6. Assignee Resolves issue with relevant Resolution when work is completed, and updates Fix Version to "Nightly/SVN-Trunk" to reflect is availability.
    • (Fixed) Most issues that reach this stage are resolved and their resolution is set to "Fixed".
    • (Won't Fix) Some issues are identified as conflicting with the expectations of the currently adopted design or represent techinical "impossibilities" and resolved as "Won't Fix", or they can be Moved to become Feature Requeests for future consideration.
  7. QA team verifies resolution of issue.
    • If it passes verification, then it is Closed.
    • If it failes verification, then it is Reopened and re-assigned for further work.

Tasks

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

Feature Requests

  1. Issue is vetted for accuracy and completeness of information.
  2. If the issue represents a broad change for Sakai, then it is treated as a Requirement, and moved to the Sakai Requirements project for further handling. (See requirements process.) Otherwise, smaller-scope suggestions, such as re-naming buttons, changing a tool's layout, choosing different defaults, etc, are left as Feature Requests and assigned to the appropriate project lead.
  3. Project team evaluates and discusses the issue as needed to determine whether to work on it.
  • If it is decided not to implement it, then the issue should be resolved as "Won't Fix" with appropriate comments.
  1. 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.

Requirements

The requirements process is still under development. During the the first requirements gathering phase over 300 issues were submitted. A rough attempt to clump and cluster related requirements resulted in over 200 requirements put forth to the greater Sakai community and the Sakai Institutional Reprsentatives for polling on relative importance; see results.

Requirement Issues which are adopted by existing Project Management Committees or Project Teams will be handled as Feature Requests are above; coverted to one or more Tasks in the Sakai Jira project to track its implementation.

Contibuted 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 Requirement, for inclusion in a future release of Sakai.
    • In some cases, a Contributed Patch may run counter to the Sakai design and cannot be incoporated, 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.

General Workflow by Task

Requirements

The workflow for the requirements process is being developed in the Sakai Working Group: Requirements Process.

Designers and Developers

Planning

  1. 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.
    • Notes on future versions:
      • Leave the Fix Version as Unknown if you are not sure what version the issue will be addressed for.
      • Set the Fix Version to the first QA release version (e.g., 2.2.1.001) to indicate an issue will be addressed for that release.

Addressing an Issue

  1. Assign a Bug or Task to yourself to work on.
  2. Work on the issue, updating, modifying, commenting, re-asssigning, etc. as necessary to achieve resolution.
  3. When work is complete, Resolve the issue as Fixed (or other appropriate resolution) and set the Fix Version to "Nightly/SVN-Trunk" (or to "Unknown", if you did not fix it.)
  4. For Tasks, if there is nothing explicit for the QA team to test, then please Close the issue. Otherwise, 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 they discover problems.)

Quality Assurance (QA)

  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 orginal problem is still present.
    • Some issues can not be easily verified and may require special testing condtions or input from developers.
  3. If the issue passes verification:
      • Verify the Fix Version is correct. (Note that an issue can have more than one Fix Version, such as being fixed in the next release plus in another version's Maintenance Branch.)
      • 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 project team leader. If is not clear to whom the issue needs to be re-assigned, then assign it to default.

Notifications

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 Peter A. Knoop.

  • No labels