Bug Reporting Guide!

[Ted]

Hey there and welcome to the Bug Tracker board.

This board is solely for the discussion of and about all issues pertaining to the The Bug Tracker. The Support & Bugs section of the Forums should be used for narrowing down an issue that you are having. Once narrowed down, feel free to post it on the Bug Tracker.

Of course, Forum Rules apply to this board and please do check if your question has already been posted.

You will need to register an account to use the bug tracker, this account is not tied in with any of your other KSP Network Accounts.

Edited September 9, 2013 by Ted

[Ted]

Bug Reporting Guide

Bug report threads that do not follow the rules will be removed, to keep the board as objective and as clean as possible.

Nothing personal. Just keeping it organized.

These Bug Reporting Rules have been kindly written by HarvesteR, with some amendments by me to keep it up-to-date, so much thanks to him for taking the time to write these. It is incredibly important that you read it all.

1. Reproducing a Bug

First of all, for us to find a bug, we need to have a way to consistently cause it to happen. So we need to know exactly how we can reproduce the issue. That means bug reports like 'I've seen this happen too, and it ruined my mission attempt' are very much meaningless to us. They just state it happened, but it doesn't help us find the source of the problem. On the other hand, extremely detailed reports of what was happening when the bug took place are also a bad idea, since we then have to dig through a wall of text to figure out what did in fact happen. Try to keep it simple, stating facts in as clean and concise a manner as possible.

2. Excluding variables

Now, the second step in properly reporting a bug, is to make sure it will happen consistently in a mod-free, clean install of the game, and using a completely new spacecraft. This will help us exclude any external variables from the problem, and things become a lot simpler. If the bug can only be reproduced with a specific spacecraft design, please include a .craft file of the simplest design where the issue still happens in your report. In cases where the issue is only present with mod parts, please make sure you isolate the part that causes the issue, and add to your report a link to where the mod may be downloaded.

3. Isolate the bug

If at all possible, try to find the minimal set of actions that will cause a bug to happen. That can be extremely helpful for us to narrow down the source of the problem.

4. Post debug information

It is very helpful to us to see the output of the debug console when these bugs take place. The debug console can be opened with Alt+F2 (RShift+F2 on Linux), and hopefully it will contain some information about what happened. If the game crashed before you could see the console, you can see the console output on the .log files that are saved in the KSP_Data folder.

5. Screenshots and videos

If a bug is too complicated to be explained in a few short sentences, videos or screenshots of it can be a lot of help. Just make sure those are as visually descriptive as possible, and wherever applicable, make annotations. It is also important that videos are uploaded as unlisted and should only be available via a link, screenshots can be uploaded to the Bug Tracker, if needed.

6. The latest version

Please make sure you are using the latest version of the game when reporting a bug. We wouldn\'t like to be chasing a bug all day, only to find that it had been already fixed on the current version. Also, if possible, reporting if the bug can also be found in a previous version can be incredibly useful to pin down a possible cause.

7. Bugs are no reason to be angry

It may sound silly, but it's very important to keep this in mind. We all know bugs are frustrating, but venting your anger on your bug report does nothing to improve it's helpfulness. In fact, all it does is hurt our morale. Please try to be as concise and objective as possible on bug reports, and avoid sentences like 'This drives me mad!' or angry smileys. That kind of comment doesn't help anyone. Think of posting a bug report as writing for Wikipedia: 'Opinionated' entries are frowned upon, and on severe cases, will be removed. Please, write in as dry, and objective, a manner as possible, stating only the bare facts.

8. The Follow-Up

Confirming that a bug has been fixed is as important as reporting the bug itself. If after addressing an issue all we hear is silence, we will never be 100% sure that the issue was indeed taken care of. If your bug got fixed, make sure you let everyone know, and flag the bug issue as solved. If it has not been fixed, please mark as Not Fixed, with details as to the effects of the attempted fix, if any, and the current behaviour of the bug, if changed. If in the rare case that the bug has been fixed, but the fix has caused another bug, please open up another issue and relate it to the previous one.

Here is an example of what we would consider an ideal bug report:

Title: [bug 0.12 x3]: Escape Trajectories reverse directions when resuming physics

What happens: When resuming real-time flight, hyperbolic orbits (escape trajectories) have their directions reversed.

How to reproduce:

* From orbit, accelerate into an escape trajectory.

* Increase Time warp factor to a minimum of 5x.

* Decrease Time warp factor back down to 1x.

* Orbital direction should have become reversed at this point.

Notes:

* Happens regardless of the planet/moon being orbited.

* Particularly noticeable on Mun capture trajectories.

Versions Affected:

Reproduceable as far back as 0.11

As you can see, the above report clearly states how the bug was encountered and how it can be reproduced with as few moves as possible. It also says the bug was reproduceable in an earlier version, which already rules out that it's not a problem with the latest modifications, but a long-standing issue. It is as helpful as a bug report can be for us, and from this we here can already point out a few suspect areas on the code where this issue could be coming from.