Bug Triaging Guidelines: Difference between revisions

From OpenMW Wiki
Jump to navigation Jump to search
(finding duplicates)
Line 20: Line 20:
Additional information / tags like environment, versions, components, etc. should be removed from the summary and communicated through other fields.
Additional information / tags like environment, versions, components, etc. should be removed from the summary and communicated through other fields.


Any typos or grammatical errors in the subject should be fixed - they might not ''seem'' like much of an issue, but over time will add up to a significant amount of time wasted as every reader has to mentally pause for a second.
Any typos or grammatical errors in the subject should be fixed - they might not ''seem'' like much of an issue, but over time will add up to a significant amount of time wasted as every reader has to mentally pause for a second. Misspellings will also trip up the search function.


== Description ==
== Description ==
Line 165: Line 165:


The operating system (OS) should initially be set to the OS of the reporter. If the issue gets Confirmed under another OS, set the OS to 'Other' to communicate the issue as non-OS specific.
The operating system (OS) should initially be set to the OS of the reporter. If the issue gets Confirmed under another OS, set the OS to 'Other' to communicate the issue as non-OS specific.
= Finding duplicates =
Typically, duplicates are caught immediately after being reported, by a member of the project that recalls the original issue. However, due to our fading memory and the growing number of issues this is not going to be a sustainable solution over the long run.
To manually find duplicates, the first tool to use is the search function. This function is somewhat clunky and only matches exact keywords. You may need to come up with many different wordings to find the actual duplicate, assuming you can find it that way at all. Failing that, you may have to read through the list of all issues of that particular category (assuming the category is non-ambigious and the original issue was categorized).

Revision as of 16:49, 18 September 2017

What is Triaging?

Bug triaging refers to assuring the quality of existing bug reports. The job of a bug triager is to:

  • Work towards Bug Reporting Guidelines being met.
  • Confirm or Reject issues.
  • Categorize and prioritise reports to make sure the relevant developer sees it.
  • Find duplicates.

How do I start?

Look at the Activity feed for recent updates or work on the list of unconfirmed bugs.

Detailed explanation of fields

Summary

A summary of the symptoms and/or the causes of the issue. Preferably just the symptoms, as causes are more difficult to ascertain and easy to get wrong.

Additional information / tags like environment, versions, components, etc. should be removed from the summary and communicated through other fields.

Any typos or grammatical errors in the subject should be fixed - they might not seem like much of an issue, but over time will add up to a significant amount of time wasted as every reader has to mentally pause for a second. Misspellings will also trip up the search function.

Description

While it may be tempting to 'clean up' the reporter's description, it would be difficult to keep track of the changes to it, or make sense of the following discussion once the original topic has been altered. It can also be frustrating for the original reporter to have part of what they reported be removed or changed without their consent.

For these reasons, editing the original description is generally discouraged. On particularly long issues, a header or footnote can be added to the description that summarizes the current state and/or resolution of the issue.

Category

The Category field refers to the code component that contains, or is suspected to contain the defect.

If there happens to be an overlap between categories, always choose the most specific category.

Category Description
AI AI related issues.
Animation Issues related to the playback of animations in models. An animation is a keyframe track used to control a visual component of the model.
Code Maintenance Issues related to the quality of the codebase, not a defect in its functionality. Code Maintenance issues should be filed under the tracker 'Task'.
Configuration Issues related to the configuration component that reads the openmw.cfg containing basic start-up configuration for the engine. Not for the user settings in settings.cfg.
Dialogue Issues related to Morrowind dialogue system.
Editor Issues only affecting our editor program, OpenMW-CS.
ESM format Issues related to the parsing of ESM/ESP game file format.
ESS-import Issues related to decoding the ESS savegame format used by the original engine, and its conversion into OpenMW's savegame format, as implemented in 'openmw-essimporter'.
Game Mechanics Related to game mechanics formulae and behavior.
General Not fitting in any other category.
GUI Issues related to the implementation of our GUI.
Input Related to input management and/or control bindings.
Launcher Issues only affecting the game launcher, openmw-launcher.
External Dependencies (MyGUI, SDL, OpenSceneGraph) Issues that originate in the source code of these dependencies and can (or should) only be fixed by changing said upstream source code. Not for issues that can be resolved by using these dependencies in different way.
NIF Format Issues related to the parsing of .nif (NetImmerse) model format, or its conversion into an OpenMW/OSG scene graph.
Packaging Not a defect in the actual source code, but in the compilation and packaging of said code into an end-user product. If possible, put the respective packager as the 'Assignee', or send them a forum PM, because they tend to not follow the tracker very closely.

Windows: Ace, MacOS: corristo, Linux generic: k1ll, Linux Debian/Ubuntu: psi29a

Should be filed under the tracker 'Task'.

Physics Related to collision detection or the movement controller.
Rendering Related to 3D rendering.
Save/Load Related to saving/loading of the gameworld.
Scripting Defect in scripting engine or specific script function(s).
Sound Related to sound playback.
Tools
Website Related to openmw.org, bugs.openmw.org or wiki.openmw.org websites.
World Model Related to the management of world state.

Status

Category Description
New Unconfirmed issue
Confirmed Claims in the issue have been verified by an independent person.
Resolved A developer has fixed the issue locally, but the fix is not included in our main repository (yet). Or the fix is in a new version of a third party dependency, but we can not enforce that OpenMW is built with said version.
In Progress Partially resolved. In most cases it is preferred to split up the unresolved parts into another issue.
Closed The fix is now available in the main repository. The 'version' field will indicate the first version to include this fix. If the issue was a recent regression on the master branch, and not present in any release, the version field shall be left empty.
Rejected The issue was invalid, for example:
  • Not our problem ( data file bug, invalid configuration )
  • Duplicate of another issue which should be linked under 'Related issues'
  • Intended behavior
  • No reasonable fix could be identified due to constraints outside of our control
  • A clarification requested from the reporter has not been given.
  • The report is very old and there is no evidence the issue still exists.

Always give an explanation for why the issue is being rejected.

Priority / Severity

Severity refers to the impact of the defect on the software and the user.

Priority is chosen based on the importance of fixing said defect. For example, a crash that only occurs under an unsupported environment would have a High Severity, but a Low Priority.

Indicators for a lower priority:

  • Only occurs under very specific conditions that can be worked around by the user.
  • Compatibility issue that occurs due to OpenMW handling content file errors more strictly, and can be easily worked around by fixing said content.

Indicators for a higher priority:

  • Regression from a previous release that is likely to make users angry
  • Possibility of data loss or breaking workflows

OS

The operating system (OS) should initially be set to the OS of the reporter. If the issue gets Confirmed under another OS, set the OS to 'Other' to communicate the issue as non-OS specific.

Finding duplicates

Typically, duplicates are caught immediately after being reported, by a member of the project that recalls the original issue. However, due to our fading memory and the growing number of issues this is not going to be a sustainable solution over the long run.

To manually find duplicates, the first tool to use is the search function. This function is somewhat clunky and only matches exact keywords. You may need to come up with many different wordings to find the actual duplicate, assuming you can find it that way at all. Failing that, you may have to read through the list of all issues of that particular category (assuming the category is non-ambigious and the original issue was categorized).