Reporting a bug

From Kokua Wiki
Jump to: navigation, search

This page contains instructions about how to use the Issue Tracker to report bugs in the Imprudence Viewer software, Kokua Viewer software, or any part of our website. Separate instructions are available for proposing a feature.

What is a bug?

Before you report a bug, it's important to understand what we consider to be a "bug". A bug is a defect or mistake in our software (the Imprudence Viewer, Kokua Viewer, or our website) that causes it to look or behave contrary to the way we intended.

Here are some examples of things that are considered bugs:

  • Some functionality or part of the viewer does not behave "as advertised".
  • The viewer crashes every time you perform a certain action or visit a certain location.
  • There is a typo or incorrect/misleading information in the viewer or on our website.

Here are some examples of things that are not considered bugs:

  • Problems caused by other software beyond our control (e.g. your operating system drivers, or the grid you are connected to).
  • Problems caused by your own mistake. (But, if the viewer or its documentation is incorrect or misleading, that is a bug.)
  • The viewer lacks a feature that other viewers have. (But, you can propose a feature.)
  • The viewer looks and behaves how we intended, but you prefer or expect a different look or behavior. (But, you can suggest we change the look or behavior; this is considered a feature proposal.)

Search for existing bug reports

Checking if a Bug or Feature already exists

Before you file a new bug report, please check to make sure it hasn't already been reported. If it has already been reported, you should not file a new bug report, since duplicate reports just waste everyone's time. But, you can update the existing issue to add a comment, attach a file, or change the issue properties to provide additional information.

You can browse the lists of current issues (i.e. both bug reports and feature proposals) here:

You can search for existing issues by typing search terms into the Search box at the top right hand side of the issues tracker page, then pressing the Enter key.

Create a new issue

Select the project you want to create an issue for
Create a new issue

Before you can create a new issue, you must register for the issue tracker and sign in.

There are three "projects" on our issue tracker. It is important to create the new issue in the correct project:

The form has many issue properties to fill out. These details help us understand the bug so we can fix it. So, it is important that you fill them out correctly, and provide an appropriate amount of detail.

Note: depending on your issue tracker account permissions, you might not be able to see or set some of these properties.

Tracker
Since you are reporting a bug, just leave it as "Bug". (If you were proposing a feature, you would select "Feature".)
Subject
Enter a brief summary of the bug. The subject should usually be less than 20 words, but it should be specific enough that someone could get an idea what the bug is about just by reading the subject. Vague subjects like "Found a bug", "Crash", or "Can't teleport" are not helpful, and make it less likely that someone will notice your report.
Description
Enter a detailed description of the bug. See the Description section below for instructions on how to fill this out.
Status
This indicates the issue's status (e.g. whether it has been fixed yet). You should usually leave this as "New". If you are submitting a patch (or Git commit) to fix the bug, select "Ready to Merge".
Priority
This indicates how severe/important the bug is. See the Priority section below for help deciding which priority to choose. If you're not sure, leave it as "Normal".
Assignee *
This indicates who has been assigned to resolve the issue. (* Only team members and contributors can set this issue property.)
Category
This indicates what sort of bug it is. See the Category section below for help deciding which category to choose. If you're not sure, leave it blank.
Target version *
This is used by the team for organizing which issues should be addressed in a particular version. (* Only team members and contributors can set this issue property.)
Affected versions
Enter the version number(s) of the viewer where you experience this bug. For "stable" (non-Experimental) versions, enter something like "1.3.0 RC2". For Experimental versions, enter only the release date (e.g. "2011.04.02"). If multiple versions are affected, enter all the affected version numbers, separated by commas, e.g. "1.3.0 RC2, 1.3.0, 1.3.1".
Has Patch
Check this box if you are submitting a patch (or Git/Mercurial commit) to fix the bug. Otherwise, leave it unchecked.
Has Repro
Check this box if a step-by-step guide to reproducing the bug is available in the Repro steps, in the issue Description, or in a comment. Otherwise, leave it unchecked.
Difficulty
Leave this blank unless you are experienced with software development. This indicates how difficult it will probably be to fix the bug.
System info
Copy and paste your full system info from the viewer (Help > About Imprudence or Help > About Kokua). If you are updating an existing issue, add your system info as a comment instead of replacing the original reporter's system info.
Repro steps
Write a step-by-step guide for how to "repro" the bug (i.e. make it happen again). See the Repro steps section below for information about how to fill this out. If you're not sure how to repro the bug, leave it blank.
Files
If you have any debug logs, screenshots, patches, or other files related to the bug, you can attach them here. Use the file chooser button to choose which file on your computer to attach. If you need to attach multiple files, click the "Add another file" link.

Description

The Description should be a detailed description of the bug, with enough information for us to diagnose, investigate, and fix the bug. Please be as detailed as possible, since we rely on the information you provide in the Description, Repro steps, and System info.

Here are some questions to consider when writing the description. You don't need to answer each question, but use them as a guide to think of relevant details to include in your description.

  • Which features or parts of the viewer are affected by the bug? In what way are they affected?
  • When did the bug first start occuring?
  • How often does the bug occur? Does it happen every time? Sometimes? Only once?
  • Is there a pattern to when it occurs? Does it happen when you perform a certain action, visit a certain location, etc.?
  • Can you reliably "repro" it, i.e. make it happen again? If so, be sure to fill out the Repro steps with a step-by-step guide.
  • Does it occur only for you, or have other people experienced it too?
  • Does it occur only on one operating system, or several? (Remember to fill in your System info.)
  • Does it occur on every grid, or just one grid? Which grid?
  • Is it related to a certain object or avatar?
  • Have you recently installed or uninstalled other softare or drivers?

Priority

The issue priority indicates how severe/important the bug is. Use the following guidelines to select the most appropriate priority. If you're not sure, leave the priority as "Normal". Intentionally exaggerating the priority will not help us fix the bug faster, but it will annoy us.

  • Minor - This bug is purely cosmetic (e.g. typo or misaligned UI); or it occurs very rarely and has few negative consequences.
  • Low - This bug occurs sometimes or affects only a small number of users; or it has minor negative consequences.
  • Normal - This bug occurs often or affects a moderate number of users; or you're not sure what priority it should be.
  • High - This bug occurs very often or affects many users; or it significantly cripples an important feature; or it's so frustrating that it makes you want to punch kittens.
  • Major - This bug makes the viewer practically impossible to use for many users.
  • Urgent! - This bug causes severe loss of data, inventory, money, or the user's life; or it must be addressed immediately to prevent the destruction of the universe.

Category

The list of available categories for a bug report varies depending on which issue tracker project you are reporting for:

Imprudence Viewer project

  • Avatar: Bugs related to avatars rendering, customization, etc.
  • Building (Prims): Bugs related to inworld building, the prim building/editing interface, etc.
  • Camera: Bugs related to the 3D camera, camera controls, etc.
  • Chat/IM: Bugs related to chat, group chat, IMs, etc.
  • Compiling: Bugs related to compiling the Imprudence Viewer itself.
  • Crash: Crashes that don't fit into any other more specific category.
  • Economy: Bugs related to money, shopping, land sales/purchases, etc.
  • Import/Export: Bugs related to the Content Backup features.
  • Inventory: Bugs related to the inventory UI, inventory loss, giving or receiving inventory, etc.
  • Inworld Audio: Bugs related to inworld sound effects (not streams or voice chat).
  • Linux: Bugs that only affect Linux, and don't fit into a more specific category.
  • Localization: Bugs related to localization and translation of the viewer.
  • Login/logout: Bugs related to logging in or out of the viewer.
  • Mac: Bugs that only affect Mac, and don't fit into a more specific category.
  • Memory Leak: Memory leaks (i.e. the viewer keeps using more and more computer memory) that don't fit into a more specific category.
  • Meta-Issue: This category is used for organizing groups of other issues.
  • Other Stuff: Bugs that don't fit into a more specific category.
  • Regression: Bugs that have been fixed in the past, but then reappeared.
  • Rendering: Bugs related to rendering, that don't fit into a more specific category.
  • Restrained Love: Bugs related to the Restrained Love/RLVa feature.
  • Scripting: Bugs related to inworld scripting and the script editor.
  • Source code: Bugs related to the Imprudence Viewer source code.
  • Spellchecking: Bugs related to the Spellchecking feature.
  • Streaming Audio/Video: Bugs related to streaming audio/video.
  • Teleport History: Bugs related to the Teleport History feature.
  • Teleporting: Bugs related to teleporting to another sim or another location in the same sim.
  • UI: Bugs related to the viewer UI, that don't fit into a more specific category.
  • Viewer Skinning: Bugs related to viewer skinning (creating the UI and UI skins).
  • Windows: Bugs that only affect Windows (operating system), and don't fit into a more specific category.

Kokua Viewer project

  • Avatar/Appearance: Bugs related to avatars rendering, customization, etc.
  • Building: Bugs related to inworld building, the prim building/editing interface, etc.
  • Camera: Bugs related to the 3D camera, camera controls, etc.
  • Chat/IM: Bugs related to chat, group chat, IMs, etc.
  • Compiling: Bugs related to compiling the Kokua Viewer itself.
  • Crash: Crashes that don't fit into any other more specific category.
  • Inventory: Bugs related to the inventory UI, inventory loss, giving or receiving inventory, etc.
  • Media Streams: Bugs related to streaming audio/video.
  • Meta Issue: This category is used for organizing groups of other issues.
  • Quality Assurance: Bugs related to our quality assurance process.
  • Scripting: Bugs related to inworld scripting and the script editor.
  • User Interface: Bugs related to the viewer UI, that don't fit into a more specific category.
  • Viewer Skinning: Bugs related to viewer skinning (creating the UI and UI skins).

If you're not sure what category to use, leave it blank.

Team Purple project

  • App Support: Bugs related to web resources used by the viewer (login screen news bar, client tag list, default grids list, etc.)
  • Blog: Bugs related to the blog (blog.kokuaviewer.org).
  • Forums: Bugs related to the forums (forums.kokuaviewer.org).
  • Git Repositories: Bugs related to our Git repositories at GitHub.
  • Issue Tracker: Bugs related to the issue tracker (redmine.kokuaviewer.org).
  • Other/General: Bugs that don't fit into a more specific category.
  • Wiki: Bugs related to the wiki (wiki.kokuaviewer.org).

Repro Steps

It's important for us to be able to reproduce your bug in order to fix it!

These take the form of:

  • Step 1.
  • Step 2.
  • Step 3. etc.
  • Observe: What actually happens.
  • Expected: What should be happening.

Here's an example repro for an imaginary bug:

  • Log in to InWorldz.
  • Teleport to InWorldz Desert Island 128,128,22
  • Open the Map.
  • Observe: Avatar dots are purple.
  • Expected: Avatar dots should be green.

Providing step-by-step information is key, as everyone's experiences are different. Without a repro, as much as me might want to track down your bug, we probably won't be able to. Other users also won't be able to search for your bug as easily and confirm it.

If you have any screenshots of your bug, please attach them as well! Being able to look at the bug in action is a tremendous help to anyone who wants to fix it.

Basically, remember this: a repro is like gold to a developer. We love to fix bugs we can reproduce, and if you want your bug to be fixed quickly, providing all the information you can is the best way to make that happen.