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 173 Next »

Update in progress... _20-Jul-2008_

The contents of this page are being updated to reflect the announced changes in our Jira practices. When possible, please follow the new practices described here. Updates to existing issues and re-configuring Jira will likely take a week so, as a result some filters may not be returning correct results during this time.

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. If you have questions regarding Jira, please send them to jira-admins@collab.sakaiproject.org.

Jira Account

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

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.

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="5675b40f-3218-4b61-9c4e-699fc2f583f6"><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.

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.

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.

Version

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

  • Affects Version - Version(s) in which an issue is observed, as is generally the case for Bugs, Feature Requests, Contributed Patches, or version "relative to which a change is planned", as is generally the case for Tasks or Branches. This should never be set to a future, unreleased version of Sakai.
  • Target Version - Version(s) for which an issue will be fixed. This could be a "future" version of Sakai, or left as Unknown (the default).
  • Fix Version - Version(s) into which the fix for an issue has been merged. This should almost always be Nightly/SVN-Trunk when first resolving an issue as Fixed, wait to add other versions, such as maintenance branches, until the appropriate merges have been completed.

Further notes on Version Numbers

  • QA Versions (e.g., 2.4.0.001, 2.4.0.002, ...) – 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 necessary for keeping it simple to search, filter, and view issues for released versions of Sakai; however, the original version numbers are still associated with each issue in the database, if there is a need to extract such information later on.
  • Branch versions as Affects Versions (e.g., Nightly/SVN-Trunk, 2.3.x, 2.4.x) – When using a branch version as an Affects Version, please also try to test the issue to see if is also an issue for the last previously tagged version. This is important because branch versions are moving targets – what is Nightly/SVN-Trunk one day is not necessarily the same the next – so it is generally more important to know if an issue affects a released version. Issues that only affect a branch version are generally quite rare.
  • Branch versions as Fix Versions (e.g., Nightly/SVN-Trunk, 2.3.x, 2.4.x) – Generally the only branch version a developer needs to be concerned with is Nightly/SVN-Trunk. Only the Branch Manager or project team members dealing with maintenance branches will need to worry about adding other branch versions (e.g., 2.3.x, 2.4.x) as Fix Versions; and, those versions should only be used when the fix is actually checked-in to the branch, it should not be used as an indication that one would like a fix checked-in. This will ensure that the issue continues to appear listed in the correct Jira filters.
  • SAK Experimental Branches (i.e., branch) – Use the generic "branch" version as the Target or Fix Version when working on subtasks under a SAK Experimental Branch. If and when the branch is merged into trunk, please rememer to update the Fix Version to the standard "Nightly/SVN-trunk" (or the appropriate maintenance branch version, if that's where its being merged).

Maintenance Branch Version Numbers

A ".x" version is used to track issues relating to maintenance branches. For instance, 2.4.x is the version number representing the 2.4 release's maintenance branch.

If someone is basing their deployment on a 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 indicate the revision number in the issue, either as part of the Summary, an additional Comment, or in the Environment field, so that folks know to which revision of the maintenance branch you are referring.

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

As a release date approaches, priorities 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 environment in which the issues was encountered, e.g., web browser, operating 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)
  • If you're reporting an issue with a maintenance branch, please include the revision number of your version of the maintenance branch here.

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

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 linked-to issue to track further progress
      3. Closed with a Resolution of "Duplicate"
      4. Target and Fix Version and should be set to "Unknown"
    • (Incorporated) If it is incorporated into a previous issue, then the newly opened issue is:
      1. Linked to the original issue as "incorporated by"
      2. Commented with a note to look at the linked-to issue to track further progress
      3. Closed with a Resolution of "Incorporated"
      4. Target and Fix Version and should be set to "Unknown"
    • (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 Bug or Feature Request.
      3. Target and Fix Version should be set to "Unknown"
    • (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.
      3. Target and Fix Version should be set to "Unknown"
    • (Cannot Reproduce) If the issue cannot be reproduced on one of the QA test servers, 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 "Cannot Reproduce"; issue can always be Reopened.
      3. Target and Fix Version should be set to "Unknown"
  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 Target Version are updated accordingly.
  5. An issue may be re-assigned to others or Watchers added to facilitate discussion of its resolution. The Priority, Target 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" (or other version in special circumstances.)
    • (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 technical "impossibilities" and resolved as "Won't Fix", or they can be Moved to become Feature Requests for future consideration.
  7. QA team verifies resolution of issue.
    • If it passes verification, then it is Closed.
    • If it fails 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.

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.

Branches

See |#Jira Branches below.

Feature Requests

  1. Issue is vetted for accuracy, completeness of information, relevance to Sakai's overall design, etc.
  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 no address the issue, then it 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.

General Workflow by Role

Community

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 creates an issue in Jira.
    • The Affects Version should be set to the released version on which their local instance of Sakai is based.
    • The Target Versions and Fix Version should be left set to the default of Unknown. The project teams will set the Target Version once they have had time to review the issue and estimate when they believe they will be able to address it. The Fix Version will be set to the version or versions of Sakai in which the fix for the issue has been merged in to the source code.

Developer

Planning

  1. As new issues come in and as you periodically review the status of existing issues, use the Target Version to indicate for what version you expect to implement a solution for the issue.
    • Notes on future versions:
      • Leave the Target Version as Unknown if you are not sure what version the issue will be addressed for.
      • Set the Target Version to the general release version (e.g., "2.4.0 [Tentative]") to indicate an issue will be addressed for that release.

Addressing an Issue

  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 Target Version to reflect for which version you expect to complete your work.
  3. Work on the issue, updating, modifying, commenting, re-assigning, etc. as necessary to achieve resolution.
  4. When work is complete, and if the resolution of the issue is Fixed, then Resolve the issue and set the Fix Version to Nightly/SVN-Trunk. If the resolution is other than Fixed (e.g., Duplicate, Non-Issue, Cannot Reproduce), then set the Target and 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.

Security Releases

To be filled in...

Maintenance Branches

See Maintenance Branch Guidelines.

Feature Branches

See Feature Branches.

Jira Branches

See Jira Branches.

Quality Assurance (QA)

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. If its not clear which version the fix was actually in, simply update it to the version on which you've just verified the issue. (Note: issues can have more than one Fix Version, such as being fixed in the next release plus in another version's Maintenance Branch, so be careful that you do not accidentally remove a previously verified Fix Version when adding your own.)
    • 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.

Maintenance Branches

See Maintenance Branch Guidelines.

Security Releases

To be filled in...

Maintenance Branch Manager

Issues that have been suggested for inclusion in a particular Maintenance Branch should have that branch's status field (e.g, 2.4.x Status, 2.5.x Status) set to "Merge". Before such issues can be merged, please verify that the meet the Maintenance Branch requirements (i.e., the issue's Resolution is Fixed and its Status is closed, meaning it has been fixed and fix has been verified against trunk code at a minimum).

Once you successfully merge an issue's fix, set the appropraite status field to "Resolved", and double-check that an appropraite Fix Version is listed.

If there is more than one Branch Manager helping maintain the branch, then you can use comments in Jira to help coordinate your work, so that you don't end up with more than one person trying to merge the same issue.

General Workflow by Task

Suggest Merge to Maintenance Branch

Set the appropraite 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, (i.e., 2.4.x Status, 2.5.x Status).

Notifications

Whenever a Jira issue is modified, the issue's Reporter, Assignee, and any Watchers will receive an email notifying them of the chage. 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.

Tips

  • All issues resolved as "Fixed" should have a Fix Version set, which generally is just "Nightly/SVN-Trunk". A tag or branch version should only be added to the Fix Version field when the fix is actually merged in.
  • All issues resolved with a resolution other than "Fixed" should not have a Fix Versions set. (The Fix Version should be "Unknown".)
  • No labels