Difference between revisions of "Bug Reporting"

From FreeSpace Wiki
Jump to: navigation, search
 
(Basic Guidelines: Edit again. Email isn't necessary since the issue tracker has ability for discussion. Also add discord link)
 
(12 intermediate revisions by 10 users not shown)
Line 1: Line 1:
 
== Places to ask about or report bugs ==
 
== Places to ask about or report bugs ==
  
[http://mgo.maxgaming.net/mantis Mantis bug reporting system]
+
* All new bugs are submitted here:
[http://www.hard-light.net/smf/index.php/board,11.0.html FSSCP Forums]
+
**[https://github.com/scp-fs2open/fs2open.github.com/issues GitHub issues page]
[http://scp.indiegames.us/forum.php FSSCP Backup Forums]
+
 
 +
* If you want to ask about bugs, you can do so on the forums:
 +
**[https://www.hard-light.net/forums/index.php/board,50.0.html FSSCP Forums]
  
 
== Basic Guidelines ==
 
== Basic Guidelines ==
  
1. Look before you leap - make sure there isn't a similar bug before you post a new one. If there is a similar bug, post info on your particular circumstance.
+
# Look before you leap - make sure there isn't a similar bug before you post a new one. If there is a similar bug, post info on your particular circumstance.
 +
# ALWAYS post what build you're using (If it's named something like "fs2_open_r", post where you got it from and what date it was posted).
 +
# ALWAYS post what command lines you're using (And which ones the bug happens with).
 +
# ALWAYS post what graphics options you are using (OpenGL/D3D).
 +
# Don't just post the bug. Post any and all relevant info, and if you aren't sure if something might be relevant - post it anyway.
 +
# If at all possible, please post contact info in the form of a Discord handle.  The Github Issue tracker does well for keeping relevant information about bugs stapled to the bug report, but sometimes a real-time conversation on [https://discord.gg/QFdueKEYrN Discord] is best.
 +
# If you've got the time, run a debug build and post any errors you get with it (Not all builds have a debug build with them though).
 +
# Keep track of any bugs you post (in)! Nothing is more annoying than not being able to close a bug simply because you don't know if it's solved or not.
 +
# Make sure to include what mediaVPs you're using.
 +
 
 +
== Error logs ==
 +
 
 +
Especially when using debug builds, FreeSpace 2 will generate files called "errorlog.txt" and more importantly "fs2_open.log" (new version of older "fs.log").
 +
 
  
2. ALWAYS post what build you're using (If it's named something like "fs2_open_r", post where you got it from and what date it was posted).
+
=== fs.log OR fs2_open.log ===
  
3. ALWAYS post what command lines you're using (And which ones the bug happens with).
+
These files - "fs.log" and "fs2_open.log" - are generally the same except the later is renamed and is placed into the main data directory instead of the root FreeSpace 2 directory (where the "fs.log" is placed)
 +
<br><br>
 +
Debug build builds new "fs2_open.log" file every time its run - even when there is no problems encountered - so make sure to gather the relevant data before running the debug build again. Posting the last five lines or so of "fs2_open.log" can be handy. Note that Notepad will not display it properly, so you'll have to open it up in Wordpad to view it properly. Posting the "fs2_open.log" in its full extent is not very useful as it contains a lot of information that debug build reports there.
 +
<br><br>
 +
In some cases it also helps to create an empty text file named "[[debug_filter.cfg]]" to the '''data''' directory under the 'root' FreeSpace 2 directory and then recreate the "fs2_open.log" file (that is to run debug build again) - with older "fs.log" file the "[[debug_filter.cfg]]" ought to be placed into 'root' FreeSpace 2 directory. This causes the debug build to gather a lot more data into the "fs2_open.log" file which may prove useful for debugging the actual issues. The "fs2_open.log" files created with "debug_filter.cfg" in use are easily over a megabyte in size often will not even open in Notepad.
 +
<br><br>
 +
If you read the "fs2_open.log" file you may notice problematic sections by yourself as well but in general '''do not post the whole "fs2_open.log"''' file - just the last five or so lines. There are also other very important sections in the "fs2_open.log" file that may help in identifying the issues. Like the section that begins with '''Building file index...''' (search for this) and ends to '''Found 21 roots and 12326 files''' (numbers may vary) as it contains information of all the various vp files the game loads. Also other sections like OpenAL initialization or OpenGL/D3D initialization may be of some use
  
4. Don't just post the bug. Post any and all relevant info, and if you aren't sure if something might be relevant - post it anyway.
+
=== errorlog.txt ===
  
5. If at all possible, post contact info. Nothing is more convenient for a dev than having an ICQ number you can use to talk with a person having a problem. It can also speed things up a lot.
+
Posting the first chunk of data from the corresponding entry in errorlog.txt can be a big help, as it may tell the dev exactly what went wrong where. (This chunk is recognizable, as it should have the date and time that the crash occured).
 +
<br><br>
 +
Most recent 'crash report' is the last one that has been listed into the "errorlog.txt". If you encounter the crash repeatedly you might want to first remove the "errorlog.txt" file from the 'root' FreeSpace 2 directory and then run the game again. Then you get only single entry to the "errorlog.txt".
 +
<br><br>
 +
Often the only useful information from the "errorlog.txt" is found from the first line of the corresponding entry.
  
6. If you've got the time, run a debug build and post any errors you get with it (Not all builds have a debug build with them though).
+
==== Example ====
  
7. Keep track of any bugs you post (in)! Nothing is more annoying than not being able to close a bug simply because you don't know if it's solved or not.
+
*The first chunk from a "errorlog.txt" entry
  
8. Make sure to include what mediaVPs you're using.
+
<pre>fs2_open_r-P4 caused an Illegal Instruction in module fs2_open_r-P4.exe at 001b:005f11b7.
 +
Exception handler called in FreeSpace 2 Main Thread.
 +
Error occurred at 1/14/2007 15:17:32.
 +
E:\Games\FreeSpace2\fs2_open_r-P4.exe, run by Unknown.
 +
1 processor(s), type 586.
 +
1024 MBytes physical memory.</pre>
  
== Posting error logs ==
+
*The first line - in this case '''fs2_open_r-P4 caused an Illegal Instruction in module fs2_open_r-P4.exe at 001b:005f11b7.''' - tells something about the error that occurred. It is also the line that ought to be included into to the error/bug reports.
  
Especially when using debug builds, Freespace 2 will generate files called "errorlog.txt" and "fs.log". Posting the first chunk of data from the corresponding entry in errorlog.txt can be a big help, as it may tell the dev exactly what went wrong where. (This chunk is recognizable, as it should have the date and time that the crash occured).
 
  
Additionally, posting the last five lines or so of "fs.log" can also be handy. Note that Notepad will not display it properly, so you'll have to open it up in Wordpad to view it properly.
+
[[Category:Source Code Project]]

Latest revision as of 02:56, 12 August 2021

Places to ask about or report bugs

  • If you want to ask about bugs, you can do so on the forums:

Basic Guidelines

  1. Look before you leap - make sure there isn't a similar bug before you post a new one. If there is a similar bug, post info on your particular circumstance.
  2. ALWAYS post what build you're using (If it's named something like "fs2_open_r", post where you got it from and what date it was posted).
  3. ALWAYS post what command lines you're using (And which ones the bug happens with).
  4. ALWAYS post what graphics options you are using (OpenGL/D3D).
  5. Don't just post the bug. Post any and all relevant info, and if you aren't sure if something might be relevant - post it anyway.
  6. If at all possible, please post contact info in the form of a Discord handle. The Github Issue tracker does well for keeping relevant information about bugs stapled to the bug report, but sometimes a real-time conversation on Discord is best.
  7. If you've got the time, run a debug build and post any errors you get with it (Not all builds have a debug build with them though).
  8. Keep track of any bugs you post (in)! Nothing is more annoying than not being able to close a bug simply because you don't know if it's solved or not.
  9. Make sure to include what mediaVPs you're using.

Error logs

Especially when using debug builds, FreeSpace 2 will generate files called "errorlog.txt" and more importantly "fs2_open.log" (new version of older "fs.log").


fs.log OR fs2_open.log

These files - "fs.log" and "fs2_open.log" - are generally the same except the later is renamed and is placed into the main data directory instead of the root FreeSpace 2 directory (where the "fs.log" is placed)

Debug build builds new "fs2_open.log" file every time its run - even when there is no problems encountered - so make sure to gather the relevant data before running the debug build again. Posting the last five lines or so of "fs2_open.log" can be handy. Note that Notepad will not display it properly, so you'll have to open it up in Wordpad to view it properly. Posting the "fs2_open.log" in its full extent is not very useful as it contains a lot of information that debug build reports there.

In some cases it also helps to create an empty text file named "debug_filter.cfg" to the data directory under the 'root' FreeSpace 2 directory and then recreate the "fs2_open.log" file (that is to run debug build again) - with older "fs.log" file the "debug_filter.cfg" ought to be placed into 'root' FreeSpace 2 directory. This causes the debug build to gather a lot more data into the "fs2_open.log" file which may prove useful for debugging the actual issues. The "fs2_open.log" files created with "debug_filter.cfg" in use are easily over a megabyte in size often will not even open in Notepad.

If you read the "fs2_open.log" file you may notice problematic sections by yourself as well but in general do not post the whole "fs2_open.log" file - just the last five or so lines. There are also other very important sections in the "fs2_open.log" file that may help in identifying the issues. Like the section that begins with Building file index... (search for this) and ends to Found 21 roots and 12326 files (numbers may vary) as it contains information of all the various vp files the game loads. Also other sections like OpenAL initialization or OpenGL/D3D initialization may be of some use

errorlog.txt

Posting the first chunk of data from the corresponding entry in errorlog.txt can be a big help, as it may tell the dev exactly what went wrong where. (This chunk is recognizable, as it should have the date and time that the crash occured).

Most recent 'crash report' is the last one that has been listed into the "errorlog.txt". If you encounter the crash repeatedly you might want to first remove the "errorlog.txt" file from the 'root' FreeSpace 2 directory and then run the game again. Then you get only single entry to the "errorlog.txt".

Often the only useful information from the "errorlog.txt" is found from the first line of the corresponding entry.

Example

  • The first chunk from a "errorlog.txt" entry
fs2_open_r-P4 caused an Illegal Instruction in module fs2_open_r-P4.exe at 001b:005f11b7.
Exception handler called in FreeSpace 2 Main Thread.
Error occurred at 1/14/2007 15:17:32.
E:\Games\FreeSpace2\fs2_open_r-P4.exe, run by Unknown.
1 processor(s), type 586.
1024 MBytes physical memory.
  • The first line - in this case fs2_open_r-P4 caused an Illegal Instruction in module fs2_open_r-P4.exe at 001b:005f11b7. - tells something about the error that occurred. It is also the line that ought to be included into to the error/bug reports.