Bug Reporting Guidelines

From OpenMW Wiki
Revision as of 11:52, 10 April 2014 by Scrawl (talk | contribs) (Config paths)
Jump to navigation Jump to search

Search for duplicates

This goes without saying - use the Search function to check if your particular issue has already been reported. Searching for the important keywords (e.g. "dead npc collision") usually works best.

Fields

Subject

Give a description of the problem, and the circumstances under which it occurs. Prefer a long, descriptive title.

Good: When opening a container and selecting "Take All", the screen flashes blue

Bad: Container issue

Please do not add additional information (e.g. OpenMW version) to the subject. This will only make it harder for us to browse the issue list. Instead, add it to the Description field.

Description

  • What version of OpenMW did you encounter the problem with? If you used a bleeding edge build, state the exact revision used.
  • What are the exact steps to reproduce the problem?
  • What did you expect to happen? What happened instead?
  • Is the problem OpenMW specific or does it also happen in vanilla Morrowind?
  • Do you use any mods? If so, does the problem also occur in a clean vanilla install without any mods?

Reproducibility

Does the problem occur everytime, or sometimes, or randomly, or did it only occur once and was not reproducible again?

Operating System

What operating system where you using when you experienced the issue? If it occurred on multiple OSes, or you are absolutely sure it is not an OS-specific issue, select Other.

Other fields

Please leave all the other fields blank. They will be filled in by the OpenMW team once we have taken a closer look at the issue.

Attach files

Screenshots/videos

Feel free to attach screenshot(s) or videos of the problem. Often this does a much better job of conveying what the problem is than a wall of text.

Savegames

If the problem occurs when loading a specific savegame, make sure to attach it. Note that savegames are not compatible across MW installations of different languages, so you should state what language your MW installation uses.

Savegames can be found in one of these folders:

  • Linux: $HOME/.local/share/openmw/saves
  • Windows: C:\Users\Username\Documents\my games\openmw\saves (username, harddrive and language may vary)
  • Mac: $HOME/Library/Preferences/openmw/saves

Logs & configuration files

Below is a list of configuration files and logs used by OpenMW that can be extremely useful for us in finding the problem. If in doubt, just zip the whole configuration folder and attach it.

Note: Please use the issue tracker's file attachment function rather than an external host (dropbox, etc) so we can be sure the files stay available as long as needed.

All configuration files and logs can be found in one of these folders:

  • Linux: $HOME/.config/openmw
  • Windows: C:\Users\Username\Documents\my games\openmw\ (username, harddrive and language may vary)
  • Mac: $HOME/Library/Preferences/openmw

OpenMW-specific

openmw.cfg

Contains the names of used esm/esp files, bsa archives, data directory and imported Morrowind.ini settings. Always a good idea to attach.

settings.cfg

Contains user settings as configured by the launcher or the ingame settings menu.

ogre.log

Contains errors and messages from Ogre3D. Also contains detailed information about your graphics card. Always attach this if you are having a graphics related issue.

MyGUI.log

GUI system messages. Always attach in case of GUI issues.

input.xml

Contains saved input bindings. Does not need to be attached, unless you are having a problem with input bindings.

Launcher-specific

launcher.cfg launcherOgre.log

OpenCS-specific

opencs.cfg opencsOgre.log

Terminal output

Always watch the terminal output. If you see errors, warnings or exceptions, make sure to attach it.

Test git master

If you are reporting issues frequently, it might be a good idea to switch to testing bleeding-edge builds. That way you can test out the newest features, and we get less reports of problems that have already been fixed in the development version.

We maintain nightly builds for Windows and an Ubuntu PPA. You can also build yourself, which is rather easy on Linux and only takes a few minutes. See Development_Environment_Setup.

Obtain a stack trace

If the problem is a crash or an exception, you can help us by providing a stack trace.

On windows, this requires having a build environment set up.

On linux, a stack trace is automatically created and a window will pop up telling you where to find it. To work properly, this requires gdb to be installed.

For non-fatal exceptions, OpenMW will not exit. To get a stack trace anyway, you need to launch OpenMW in the debugger and tell it to break on exceptions. For gdb, this can be done with the 'catch throw' command.

Bisect

If the problem is a regression, i.e. earlier versions of OpenMW did not suffer from the problem, you can help us by identifying the revision that introduced the problem. The git bisect tool makes this very easy. You need a build environment set up to do this.

Start the bisect process using:

git bisect start

Mark the HEAD revision as bad:

git bisect bad HEAD

Mark a tag or revision as good (you can get a list of all tags using git tag -l):

git bisect good openmw-0.29.0

A revision will now be checked out and you need to build and test whether the problem exists in this revision. If a revision fails to build for some reason, do

git bisect skip

to skip it. Once you have found a good or bad revision, mark it using either

git bisect good

or

git bisect bad

Now git will checkout the next revision to test. Repeat this process until the first bad commit has been found. Usually this will only take a couple of steps, since it is a binary search.