How to Write a Good Bug Report

For very in-depth guidelines on how to report bugs in a way that assists the programmer, check out this article. 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 either Codeberg or GitHub.

You will need to have an Account on either Codeberg or GitHub. You can choose whichever of these two you prefer.

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.

If you are unable or unwilling to use Codeberg or 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)
• 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 Codeberg or 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 Codeberg and GitHub for questions
• ask them on chat
• raise hands in despair, listen to Despair, fall on the floor, watch as everyone else becomes a dinosaur (or at least an Atlantean)