Versions Compared

Key

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

...

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.

Tip
titleJira 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 self-register for an account from jira-admins@collab.sakaiproject.org. by clicking on the "Sign-Up" link in the login dialog.

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 . You need a separate username and password for each system.

...

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="916578cd51ceca01-9570f57a-4c3b4daf-b599a0c4-ed022c3a9d738ebb6916fb1b"><ac:plain-text-body><![CDATA[

Contributed Patch

A community-contributed patch to a particular version of sakaiSakai. 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 original issue in order to track Sakai's work on the issue. [Use at your own risk!]

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

...

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

Anchor
Priority
Priority
Priority

...

In practice, the Jira Priority field is utlized utilized by Sakai at two times: during prioritization of requirments requirements 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 priorities will also be adjusted – and lowered, if necessary – to reflect the decreasing availability of time and resources.

...

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

Anchor

...

Environment

...

Environment
Environment

  • A description of the Sakai enivronment environment in which the issues was encountered, e.g., web browser, operatings 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.

Anchor

...

Description

...

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

...

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

...

  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"
    • (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 obatain 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 techinical technical "impossibilities" and resolved as "Won't Fix", or they can be Moved to become Feature Requeests Requests for future consideration.
  7. QA team verifies resolution of issue.
    • If it passes verification, then it is Closed.
    • If it failes fails verification, then it is Reopened and re-assigned for further work.

...

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 Representatives 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 converted to one or more Tasks in the Sakai Jira project to track its implementation.

Anchor
Contributed Patches
Contributed Patches
Image Modified

...

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

...

  • User posts a Feature Request or a Contributed Patch
  • Small requests (e.g., correct the grammar of this sentence, turn this red) are separated from major requests (e.g., reconfigure the interface for Resources to eliminate all the links next to each file, add a way to view all the contirbutions contributions across tools a student has made in a site) for new or modified functionality. The simple requests are handed off directly to project teams for evaulation evaluation as to whether or not to implmentimplement. The more complex requests enter the Requirments Requirements workflow, as outlined below.
    • Requirments Requirements are vetted to ensure that they are clearly stated and supported by examples and use cases. Suggestions on implementation strategies are separaeted separated out from the description of the requirement in order to re-inforce enforce the need identifed identified in the requirement. This process may require discussion, via comments in Jira, with the original issue Reporter, members of appropriate project teams and associated working groups.
    • Once a year, requirements are posted for a community ranking poll.
    • The opinions expressed in that poll are shared with the community and with the project teams. The project teams are encouraged to take them into consideration when planning their work for subsequent releases. The community is encouraged to volunteer to help out with implemention implementation of requirements that were important to them by providing resources (programmers, designers, QA, etc.).

...

  1. Assign the issue to yourself to work on.
  2. If you are implementing a Feature Request, Requirement, 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-asssigningassigning, 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 resoultion 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.

...

  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 original problem is still present.
    • Some issues can not be easily verified and may require special testing condtions 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 accidently 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.

...

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 cople couple of strategies for monitoring Jira issues en masse:

...

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

Anchor
Tips
Tips
Tips

  • All issues resolved as "Fixed" should have a Fix Version set.
  • All issures resolved with a resolution other than "Fixed" should not have a Fix Versions set. (The Fix Version should be "Unknown".)
  • When resolving an Issue as Fixed, you generally want to set the Fix Version to Nightly/SVN-Trunk, as that is where you are typically fixing an issue.