How to Write (Good) Bug Reports

Merely writing a post about a problem is often not sufficient for having the problem fixed. Coders need to understand what exactly happened and usually need to be able to repeat the problem themselves. Therefore, the better bug report you provide, the better are the chances it will get fixed, and if the bug report is poor, it may be impossible to fix the problem. Remember that X:CE coders work on X:CE in their spare time, which is limited. The more work you do for them, the more time they will have for actually fixing the problem (and, conversely, poor bug reports will less likely get fixed).

Summary:

• Use a descriptive title including game version.
  
• Provide a description of the problem and exact steps to reproduce it.
  
• Provide a screenshot and a saved game.
  
• Provide a list of mods and local modifications you use.
  

Title:

A good and descriptive title of the bug report helps to quickly understand what the bug is about a prioritize it. Bug reports with vague titles are more likely to get low priority. Try to sum up the problem and what is specific about it.

Prefix the title with the game version, such as "[X:CE 0.30]" (the game version can be seen in the game launcher).

Good:

[X:CE 0.28] Changing Dropship Name causes Crash

[X:CE 0.28] Crash upon completion of the final mission

Bad:

• "Few issues" - what few issues?
  
• "Game crashes" - vague
  
• "Help" - bug reports are not a support forum
  
• "Bug!" - you don't say
  

Description:

The bug report description should make it clear what the problem is and make it possible for coders to try it out themselves. The more time coders have to spend figuring out what the problem actually is and how to see it, the less time they have to fix it (and the less likely they will work on the bug). If it's unclear what exactly lead to the problem, try to be as specific as possible.

It is especially helpful to provide step-by-step instructions on how to reproduce the problem. Many actions can be performed in several ways (for example a grenade can be throw from hand or from quickthrow slot) and the problem may be triggered only in some of them. Provide instructions how to be able to repeat the problem.

If it is not obvious, also say what you expect should happen instead and why.

Good:

Renaming a dropship causes game crash.

Steps to reproduce:

- Start a new game and place a base.

- Go to "Aircraft Equipment" base tab.

- Go to "Dropships".

- Click "Rename aircraft" and rename Charlie - 1 to e.g. Delta - 1.

- Go to "Barracks" base view and notice that soldiers are now assigned to non-existent "Charlie - 10".

- Go back to "Dropships" and click on one of the soldiers.

- The game will crash.

Bad:

• "I threw a grenade at an alien and the game crashed." - What grenade, how was it thrown, at what alien?
  
• "I did something and the game crashed." - what something?
  
• "The game crashed." - you don't say
  

Screenshot, saved game:

A screenshot and a saved game can help to quickly understand the problem and be able to reproduce it, so if possible, providing them will may save coders a lot of time and thus make it more likely your problem will be fixed. Especially a game save may be very useful, as it can take a lot of time to re-create the specific scenario of the problem.

If a bug report will not provide a way for coders to see the problem for themselves, it is not very likely they will be able to do anything about the bug, as it is usually hard (and often impossible) to fix problems without being able to reproduce them. As such, bug reports without good steps to reproduce and/or a saved game are usually practically pointless.

Saved games are located in the folder selected in the game launcher (by default Xenonauts folder in the Documents), and they can be attached to posts using "Manage attachments" in advanced options.

The save should show game state before the problem occurs, not after. A save done after a problem has already happened may prove the problem exists, but it may be useless for seeing how it happened. If it is hard to estimate when a problem will occur (and thus save before), it is possible to enable endTurnAutosave option in gameconfig.xml, which will automatically create a save called Endturnautosave.sav whenever you end a turn in ground combat. Installing [ATTACH]5597[/ATTACH] using Modding Tools in the launcher will enable this option. You should immediately back up the save, as ending another turn will overwrite the save.

Please verify that your saved game and steps to reproduce actually show the problem. If it happens only sometimes, provide a guess at roughly how often the problem does and does not happen.

List of mods and local modifications used:

Provide a full list of mods that you use. Some saved games do not work without having the same mods installed. Some problems may be caused by mods and do not exist with unmodded game.

Similarly, provide a list of local configuration changes if they might be relevant.

Example:

[X:CE 0.28]Windows count as cover only if they are broken first

If a soldier is taking cover behind a window that is not broken, the window actually does not act as a cover. It starts acting as cover only when it is broken. This does not make sense, as a window with glass in it should provide at least the same cover as a window with the glass broken.

(screenshot showing the situation described below - not really necessary in this case as the steps to reproduce make it obvious and the saved game makes it easy to test)

(saved game)

Steps to reproduce:

- load the saved game

- select Sgt. Lukas Cerny

- click the weapon to enter fire mode and aim at Cpl. Helma Hartmann

- notice that the window is not shown as a block and the chance to hit is 26%

- aim at the window and shoot it in order to break it

- repeat aiming at Cpl. Helma Hartmann

- notice that the window is shown as 50% block and the chance to hit is 13%

Mods used: Time Units First, Select Next Soldier, Khall's More Portraits, Skitso's Ultimate Megamix Map Pack 2000, Armoured Assault

Configuration changes: PercentageWeaponCosts=0

endturnautosave.zip

endturnautosave.zip