Bug Reporting Guidelines: Difference between revisions

From OpenMW Wiki
Jump to navigation Jump to search
(→‎Description: added in-game location question)
(More GitLab-related fixes)
 
(38 intermediate revisions by 9 users not shown)
Line 1: Line 1:
== Where to be ==
You can find the bugtracker on [https://gitlab.com/OpenMW/openmw/issues our GitLab repository]. Before you can report a bug, you'll have to [https://gitlab.com/users/sign_in register an account]. After that, you can log in by going to the the same page and using Sign in form.
After logging in, go to the issues page once more. You can now submit a bug by clicking on "New Issue". Before you do that, be sure to search for duplicates!
== Search for duplicates ==  
== 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.  
Before doing anything else, use Search to check if your particular issue has already been reported. Try searching for keywords describing your issue (e.g. "dead npc collision"). If that didn't work, try using Google.


== Fields ==  
== Fields ==  
Line 10: Line 15:


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


'''Bad:
'''Bad:
Line 16: Line 21:


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.
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.
Note: If your bug is related to the OpenMW editor, OpenMW-CS, append "Editor: " to the beginning of your subject string. Do not amend the subject of existing bugs that may have the prefix, "OpenMW-CS: ".


=== Description ===
=== Description ===
Line 22: Line 29:


* Is the problem OpenMW specific or does it also happen in vanilla Morrowind?
* Is the problem OpenMW specific or does it also happen in vanilla Morrowind?
* What version of OpenMW are you using? If you used a bleeding edge build, state the exact revision used.
* What version of Morrowind are you using (i.e. retail CD or Steam)? What addons (Tribunal, Bloodmoon) do you have installed? What language is your Morrowind install?
* Do you use any mods? If so, does the problem also occur in a clean vanilla install without any mods?
* Do you use any mods? If so, does the problem also occur in a clean vanilla install without any mods?
* What version of OpenMW did you encounter the problem with? If you used a bleeding edge build, state the exact revision used.
* Are you using any [https://openmw.readthedocs.io/en/master/reference/modding/settings/index.html Advanced settings] in your settings file? If so, try reverting to the default settings to see if that changes your issue. Many of these settings are experimental and not widely tested. Note that an improper settings file may cause the game to crash or misbehave; and recent changes to the codebase will sometimes inadvertently break certain configurations.
* What are the exact steps to reproduce the problem?
* What are the exact steps to reproduce the problem?
* What did you expect to happen? What happened instead?
* What did you expect to happen? What happened instead?
* Where is the in-game location this problem can be observed? Avoid vague statements such as "west of town X". Instead, use the getpos console commands to get the exact location. When done, you can copy the results to the system clipboard.
* Are there any error messages in the openmw.log file (see [[Bug_Reporting_Guidelines#Logs_.26_configuration_files Logs & configuration files]]?
* Where is the in-game location this problem can be observed? Avoid vague statements such as "west of town X". Instead, open the console (<code>`</code> key by default, the key above Tab), click on the problematic object, then use the betacomment (bc) instruction:
 
<pre>
<pre>
player->getpos x
bc
player->getpos y
player->getpos z
</pre>
</pre>


=== Reproducibility ===
It will print lots of useful information about the object that you can copy and paste into the bugreport:
 
<pre>
Does the problem occur everytime, or sometimes, or randomly, or did it only occur once and was not reproducible again?
Content file: Morrowind.esm
RefID: ex_nord_door_01
Cell: Caldera
Coordinates: Vector3(-12472, 20680, 1652)
</pre>


=== Operating System ===
=== 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.  
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, don't select a label.


=== Other fields ===
== Attach files ==
 
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 ==
'''Note''': Where possible, please use the GitLab file attachment function rather than an external host (dropbox, etc) so we can be sure the files stay available as long as needed.


=== Screenshots/videos ===
=== 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.
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.
If you are reporting a performance issue, make sure to include a screenshot of [[Profiling]] output.


=== Savegames ===
=== 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.
If the problem occurs when loading a specific savegame, make sure to attach it.


See [[Paths]] for the location of save files.
See [[Paths]] for the location of save files.
It is a good idea to compress savegames before uploading them (.7z, .rar, .zip, ...) and will also make it less likely to exceed the filesize limit of the bugtracker (5 MB).


=== Logs & configuration files ===
=== Logs & configuration files ===
Line 62: Line 77:


See [[Paths]] for the location of logs & configuration files.
See [[Paths]] for the location of logs & configuration files.
'''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.


==== OpenMW-specific ====
==== OpenMW-specific ====


openmw.log (Used by OpenMW 0.31 and later versions)
* openmw.log: Contains game messages and errors.


Contains game messages and errors.
* openmw.cfg: Contains the names of used esm/esp files, bsa archives, data directory and imported Morrowind.ini settings.


openmw.cfg
* settings.cfg: Contains user settings as configured by the launcher or the ingame settings menu. 


Contains the names of used esm/esp files, bsa archives, data directory and imported Morrowind.ini settings. Always a good idea to attach.
* input_v3.xml: Contains saved input bindings. Does not need to be attached, unless you are having a problem with input bindings.


settings.cfg
==== Launcher-specific ====
 
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
* launcher.cfg


GUI system messages. Always attach in case of GUI issues.
==== OpenMW-CS-specific ====
 
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
* openmw-cs.cfg
launcherOgre.log


==== OpenCS-specific ====
== Stick around ==


opencs.cfg
After you've reported the issue, make sure to check back occasionally (or enable email notifications) in case we require more information from you.
opencsOgre.log


==== Terminal output ====
== Explanation of issue states ==


Always watch the terminal output. If you see errors, warnings or exceptions, make sure to attach it.
* ''Closed'' - either the fix is now available in the main repository, or the issue was rejected for one of the following reasons. If you still see the issue happening, then complain!
** 1. It is a duplicate of another issue that was already reported earlier (watch for "Duplicates #XYZ" in the activity log).
** 2. It is a bug in the game data, and not in the engine, so OpenMW cannot fix it.
** 3. The bug is not reasonably fixable due to constraints outside of our control.
Do not get discouraged when some of your issues get rejected, and feel free to continue reporting any other issues you find.


== Test git master ==
== Test git master ==
Line 117: Line 120:
On windows, this requires having a build environment set up.
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.
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.
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.
Line 127: Line 130:
Start the bisect process using:
Start the bisect process using:


git bisect start
  git bisect start


Mark the HEAD revision as bad:
Mark the HEAD revision as bad:


git bisect bad HEAD
  git bisect bad HEAD


Mark a tag or revision as good (you can get a list of all tags using git tag -l):
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  
  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
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
  git bisect skip


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


git bisect good
  git bisect good


or
or


git bisect bad
  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.
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.
[[Category:Testing]]
= Model-specific problems =
If the problem is with a specific model, you can try disabling optimizations to see if that fixes the issue. If that is indeed the case, we definitely have a bug. See [[Rendering Architecture#Optimizer]] for instructions.
In any case, you can greatly speed up the resolution of your issue by extracting some information from the model and posting it with your bug report. Please consider including:
* A screenshot of the model opened in [[Tools#NifSkope]] (with as many nodes as possible and/or relevant ones expanded).
* From within OpenMW, open the console, click on the model, type 'ShowSceneGraph', then attach the created file.
= See also =
[[Bug Triaging Guidelines]]

Latest revision as of 18:18, 19 June 2018

Where to be

You can find the bugtracker on our GitLab repository. Before you can report a bug, you'll have to register an account. After that, you can log in by going to the the same page and using Sign in form.

After logging in, go to the issues page once more. You can now submit a bug by clicking on "New Issue". Before you do that, be sure to search for duplicates!

Search for duplicates

Before doing anything else, use Search to check if your particular issue has already been reported. Try searching for keywords describing your issue (e.g. "dead npc collision"). If that didn't work, try using Google.

Fields

Subject

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

Good: Screen flashes blue when opening a container and selecting "Take All"

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.

Note: If your bug is related to the OpenMW editor, OpenMW-CS, append "Editor: " to the beginning of your subject string. Do not amend the subject of existing bugs that may have the prefix, "OpenMW-CS: ".

Description

Describe the issue as detailed as you can. Below is a list of questions that should be answered in the description (if they apply).

  • Is the problem OpenMW specific or does it also happen in vanilla Morrowind?
  • What version of OpenMW are you using? If you used a bleeding edge build, state the exact revision used.
  • What version of Morrowind are you using (i.e. retail CD or Steam)? What addons (Tribunal, Bloodmoon) do you have installed? What language is your Morrowind install?
  • Do you use any mods? If so, does the problem also occur in a clean vanilla install without any mods?
  • Are you using any Advanced settings in your settings file? If so, try reverting to the default settings to see if that changes your issue. Many of these settings are experimental and not widely tested. Note that an improper settings file may cause the game to crash or misbehave; and recent changes to the codebase will sometimes inadvertently break certain configurations.
  • What are the exact steps to reproduce the problem?
  • What did you expect to happen? What happened instead?
  • Are there any error messages in the openmw.log file (see Bug_Reporting_Guidelines#Logs_.26_configuration_files Logs & configuration files?
  • Where is the in-game location this problem can be observed? Avoid vague statements such as "west of town X". Instead, open the console (` key by default, the key above Tab), click on the problematic object, then use the betacomment (bc) instruction:
bc

It will print lots of useful information about the object that you can copy and paste into the bugreport:

Content file: Morrowind.esm
RefID: ex_nord_door_01
Cell: Caldera
Coordinates: Vector3(-12472, 20680, 1652)

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, don't select a label.

Attach files

Note: Where possible, please use the GitLab file attachment function rather than an external host (dropbox, etc) so we can be sure the files stay available as long as needed.

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.

If you are reporting a performance issue, make sure to include a screenshot of Profiling output.

Savegames

If the problem occurs when loading a specific savegame, make sure to attach it.

See Paths for the location of save files.

It is a good idea to compress savegames before uploading them (.7z, .rar, .zip, ...) and will also make it less likely to exceed the filesize limit of the bugtracker (5 MB).

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.

See Paths for the location of logs & configuration files.

OpenMW-specific

  • openmw.log: Contains game messages and errors.
  • openmw.cfg: Contains the names of used esm/esp files, bsa archives, data directory and imported Morrowind.ini settings.
  • settings.cfg: Contains user settings as configured by the launcher or the ingame settings menu.
  • input_v3.xml: Contains saved input bindings. Does not need to be attached, unless you are having a problem with input bindings.

Launcher-specific

  • launcher.cfg

OpenMW-CS-specific

  • openmw-cs.cfg

Stick around

After you've reported the issue, make sure to check back occasionally (or enable email notifications) in case we require more information from you.

Explanation of issue states

  • Closed - either the fix is now available in the main repository, or the issue was rejected for one of the following reasons. If you still see the issue happening, then complain!
    • 1. It is a duplicate of another issue that was already reported earlier (watch for "Duplicates #XYZ" in the activity log).
    • 2. It is a bug in the game data, and not in the engine, so OpenMW cannot fix it.
    • 3. The bug is not reasonably fixable due to constraints outside of our control.

Do not get discouraged when some of your issues get rejected, and feel free to continue reporting any other issues you find.

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.

Model-specific problems

If the problem is with a specific model, you can try disabling optimizations to see if that fixes the issue. If that is indeed the case, we definitely have a bug. See Rendering Architecture#Optimizer for instructions.

In any case, you can greatly speed up the resolution of your issue by extracting some information from the model and posting it with your bug report. Please consider including:

  • A screenshot of the model opened in Tools#NifSkope (with as many nodes as possible and/or relevant ones expanded).
  • From within OpenMW, open the console, click on the model, type 'ShowSceneGraph', then attach the created file.

See also

Bug Triaging Guidelines