Latest Posts

Changes in How to Write a Good Bug Report

Revision Differences of Revision 41

[TOC] ¶

For very in-depth guidelines on how to report bugs in a way that assists the programmer, check out this [article](http://www.chiark.greenend.org.uk/~sgtatham/bugs.html). It is available in a number of languages. ¶

##1. Where to report the bug ¶

The best way to report a bug is to craft a bug report at [GitHub](https://github.com/widelands/widelands/issues). ¶

You will need to have an Account on GitHub. ¶

On the right hand side you will find a green button "New issue". Clicking it, you will be offered a choice between reporting a bug or requesting a new feature. ¶

Before filling out a Bug Report, use the "Search" function to see if your problem has already been addressed. ¶

If your bug is not listed or nothing was found, click "New issue" -> "Bug report" to fill out the form with the needed information (see below) and optionally attach files. ¶

If you are a project maintainer, do not forget to add the proper tags after submitting your issue - if you are not sure about the tags just invent some or leave the field empty and we will add them later on. ¶

For more help specifically with GitHub, check [here](https://help.github.com/en/github/managing-your-work-on-github/about-issues). ¶

**If you are unable or unwilling to use GitHub, mention the bug in the "Technical Help" Forum here: <https://wl.widelands.org/forum/forum/1/>.** ¶



##2. Operating System Information ¶

Please provide ALL of the following information: ¶

* Operating System (OS) and patch level/kernel: ¶
* e. g.: Windows XP SP3 ¶
* e. g.: Xubuntu 12.04.3, Linux xubuntu 3.8.0-35-generic #52~precise1-Ubuntu SMP Thu Jan 30 17:24:40 UTC 2014 x86_64 x86_64 x86_64 GNU/Linux ¶


* Widelands release: ¶
* e. g.: 17 ¶
* e. g.: bzr6826 ¶
* e. g.: 1:17-ppa0-bzr6827-201402020556~ubuntu12.04.1 ¶



##3. Description of the problem ¶

Describe the error / bug / false behaviour as specifically as possible: ¶

* The best idea is to use the tile line from crash report: ¶

* e. g.: widelands crashed with SIGSEGV in \__GI__pthread_mutex_lock() ¶


* Think about your headline; try to be succinct as well as descriptive. ¶

* e. g.: wanted to attack the enemy --> no soldier attacks ¶
* e. g.: game crashed while opening up statistic details ¶


* Describe what you did and what you expected to happen, as well as what actually occurred. ¶

Again, be descriptive, but try not to write the next A Song of Ice and Fire or installment of Linux from scratch. ¶



##4. Hardware ¶

If you believe the trouble could depend on your hardware, be sure to indicate this in the bug report or as an attachment: ¶

* Mainboard and CPU ¶
* RAM ¶
* Graphics card ¶
* SSD/HDD and extraordinary configuration (RAID ?; LVM2 ?; ...) ¶
* Network card (?) ¶
* Sound card (?) ¶

* e. g.: Gigabyte GA-MA790GP-UD4H F7c w/ AMD Phenom II X4 810 + 2× 2×2048 MB AData DDR2 800 MHz; Gigabyte GV-R667D3-2GI; 64 GB AData SP900 /; 2×1 TB Seagate ST31000523AS /home (LVM2) + 1.5 TB Seagate ST31500521AS /pub; Pioneer BDR-208DBK ¶

If you do not know exactly which hardware elements you are referring to, check the following: ¶

* in the system management (Start --> Execute... --> compmgmt.msc --> Device Manager --> ) ¶

* in "Terminal" by typing "sudo lshw > lshw.txt" ¶

* look on in your manual and/or bill(s), if you bought single components ¶



##5. Savegames and Replays ¶

Attach save games and/or replays. The way to do this is dependent on your OS: ¶

###5a. Apple Operating Systems ¶


* Mac OS X: Open Finder. ¶
In the Menu "Go" click on "Go to Folder". Enter "~/.widelands" and press return. ¶

This will open a hidden folder in your home directory that contains Widelands files. ¶
In the "save" directory you will find your save games and the replays are in "replays". ¶



###5b. Microsoft Operating Systems ¶

* Windows XP and Vista: C:\\Documents\\[username]\\.widelands ¶

* Windows 7 and 8 / 8.1: C:\\Users\\[username]\\.widelands ¶

In the "save" directory you will find your save games and the replays are in "replays". ¶



###5c. GNU/Linux ¶


* /home/[username]/.widelands ¶
* tested with Ubuntu and Fedora ¶

In the "save" directory you will find your save games and the replays are in "replays". ¶

##6. Getting a backtrace for a crash ¶

Providing a backtrace is advanced stuff, but if you are Linux user, it is not that complicated. You will need: ¶

* A debug build of the game (this might mean [compiling the game yourself](https://wl.widelands.org/wiki/Building%20Widelands/)) ¶
* *gdb* debugger installed (this is a common package that should be available in your distribution's software package repository) ¶

gdb is best used from a terminal and the session might look like this: ¶

gdb ./widelands ¶
....... # takes 1-3 seconds to pre-load the game ¶
(gdb) run # type run and optionally with command line switches ¶
....... # if a crash happened, you will get the prompt again: ¶
(gdb) bt # type bt and bt will be printed out. ¶

There is an easier way how to get this (especially because fullscreen mode can make typing into console impossible). You can use just this one-liner: ¶

~~~~ ¶
gdb -batch -ex "run" -ex "bt" ${widelands binary with path if needed} > ${log with gdb output} 2>&1 ¶
~~~~ ¶

the actual command can look like: ¶

gdb -batch -ex "run" -ex "bt" ./widelands >> gdb.log 2>&1 ¶

This will start the game. Just play as usual and if the game crashes, the file `gdb.log` will contain all console output including a gdb backtrace at the end of the file. Then you can provide it as a part of a bug report. Alternatively if you are using localization it may be convenient to force english in the output with: ¶

LC_ALL=C gdb -batch -ex "run" -ex "bt" ./widelands >> gdb.log 2>&1 ¶

With exception of situation when the crash is caused by localization itself of course. ¶

##7. Reporting a crash ¶

If you had a crash, attach the file to the bug report. ¶

The path differs according to your OS: ¶

* Mac OS X: The file is not written by default. Just try to explain as good as you can. ¶

* Microsoft OS's: C:\\Programs\\Widelands\\stdout.txt (or wherever you installed Widelands) ¶
* In new version, a stdout.txt in not created automatically. To do so, you have to start Widelands via the command line. For example: ¶
* Go to C:\\Programs (or wherever you installed Widelands) ¶
* Shift + right-click on the Widelands directory. Choose "Open command prompt". ¶
* In the new window, type `widelands.exe 1>stdout.txt 2>stderr.txt`. Widelands is now started, and the output goes to the respective files. They are overwritten everytime you do this. ¶

* GNU/Linux: /var/crash/ ¶

**Is Widelands installed via ppa you will get a message, that an automatic report is not possible cause of third party packages.** ¶

In this case you can report the bug / crash via GitHub and add the crash report as an attachment. ¶
If a error message about missing rights comes up, just copy the crash report into your home directory and change the permissions: ¶

* e. g.: sudo cp /var/crash/_usr_games_widelands.1001.crash . (<-- don't forget this point :) ) ¶

* than: sudo chown laza: _usr_games_widelands.1001.crash (<-- make sure, you correct 'laza' into YOUR username!) ¶


The number in the crash report can slightly differ from 1001, so look out for the actual one and check date and time! ¶



##8. Still have more questions about bug reporting? ¶

Cannot figure it out on the damn machine? Struggling with my bad English or this guide? ¶

Try in this order: ¶

* search in the Forums ¶
* search on GitHub for questions ¶
* ask them on [chat](/webchat) ¶
* raise hands in despair, listen to Despair, fall on the floor, watch as everyone else becomes a dinosaur (or at least an Atlantean)