Appendix B: Sending a Bug Report
From X-Plane Wiki
When sending a bug report, please include as much information as possible—anything that the X-Plane development crew might need to know in order to reproduce the malfunction. This includes (but is not limited to) the following information:
- The software in question (X-Plane, EFIS-App, Plane-Maker, etc.)
- The operating system being used
- The version of X-Plane in question
- The hardware in use (if the issue only occurs when using certain hardware)
- The exact steps (as specific and step-by-step as possible) required to reproduce the problem
Additionally, before filing a bug report, please:
- Be sure you are using the latest version of X-Plane (this includes making sure you aren’t using an outdated shortcut).
- Delete (or change the name of) your preferences file in order to rule that out.
- Disable any plug-ins or third-party add-ons. (Please report bugs in third-party software to the software’s developer, not the X-Plane team.)
- Be sure you understand the feature you are reporting a bug on.
- Contact X-Plane customer support at email@example.com if you are not sure whether you have a bug or a tech support problem.
- Attach a log.txt file from X-Plane (or the installer or other X-Application) when filing the report, as well as PNG screenshots for any visual problems. The log.txt file will tell us a lot of information about your system that will speed up bug analysis.
To file a bug report, please use this page.
Please note that, if the report was filed correctly, you will not receive any feedback on it. The report will be saved and looked into, and, depending on its priority, fixed in a future update.
Below is an email that gets sent often when users send a bug report without enough information to diagnose the problem:
Very often, people will report a bug like, "My speed indicator does not work.” Well, I might crash my Corvette into a tree, pick up my cell phone as the airbag deflates in my lap, call General Motors, and say, "My speed thing indicates zero!"
In a case like that, how good a job can GM do in deciphering that report?
Filing a report with X-Plane saying “My speed indicator does not work" can be almost that incomplete for two reasons. The first is that with about 20 or 30 instruments available in the X-Plane world (accessible via Plane-Maker) that indicate speed, saying "speed Indicator" does not really isolate what instrument is being discussed. The second reason is that you have not really given a checklist of steps that you took to find yourself with the apparent bug. For example, it may take certain conditions for the airspeed indicator to not work, conditions you may cause without thinking about based on your airplane selection, weather, etc.
In my Corvette analogy, the proper report to GM would be:
- 1. I got in my car.
- 2. I hit the starter button, the engine started, and I put the transmission in first gear.
- 3. I hit the gas and turned the wheel and drove until I hit a tree, which stopped me.
- 4. The speedometer in the instrument panel indicated zero.
- 5. I included a picture I took on my digital camera here, showing both the speedometer indicating zero and the car actually stopped.
In the X-Plane world, a proper checklist for the report would look like:
- 1. I deleted my preferences so I did not have any odd settings that may cause this that we might not know about.
- 2. I fired up X-Plane on computer running [insert operating system here].
- 3. I went to the File menu and opened the “Austin’s Personal Transport” aircraft.
- 4. I noticed the EFIS airspeed indicator stayed at zero, no matter how fast I flew.
- 5. I included a screenshot of X-Plane showing the panel here, with the actual speed of the plane shown using the Data Output screen to show my real speed.
The difference between the five-lined report above and the one-liner at the top is that you have actually told me what you are really doing. You are starting by deleting the preferences so that I can do the same as you (a first step toward solving the problem!), you are telling me what plane you are opening (so I can do the same), you are choosing one of the planes that come with X-Plane (so I can do the same as you) and you are listing which of X-Plane's dozens of speed indicators you are referring to, so I can see what the problem really is.
To summarize the above, be sure to give a complete checklist to duplicate the issue, starting with deleting the preferences and choosing an airplane that comes with X-Plane so that I can go through the same steps as you. I must be able to mirror your actions, step by step, to duplicate the bug on my computer, as this is the first step to solving the problem.
Another very common mistake is to say something like, "I flip a switch and hit a button and an indicator goes to 56%." The problem with this is that it doesn’t tell what the issue actually is. What do you think the indicator should go to? And, above all, prove it.
In almost all filed bug reports, the report lacks any sort of proof that the value being cited as wrong is actually wrong. Since I sometimes get reports from people that think a Cessna cannot roll, an airliner cannot take off without flaps, or a helicopter cannot turn without pulling collective (all incorrect assumptions on the part of the “bug” reporter), I do require proof that a characteristic that is claimed to be wrong actually is. Segments of pilot's operating handbooks are typically just fine.
So, be sure to include proof that a characteristic of the simulator is wrong if you believe it to be so.
Another very common error is for people to install plug-ins that modify data in the sim, third-party scenery packages that don't quite follow the standards, or third-party airplanes that may have problems, and then report it as a “bug” when something does not work correctly.
I won’t be able to duplicate the problem if it is due to third-party modifications. So, be sure that starting from a freshly installed copy of X-Plane with the preferences (and any plug-ins) removed is the first item in your step-by-step walkthrough for recreating the problem. Build up from there as needed, including each step in the checklist so that I can go through it and see the same thing you see. Use only scenery and planes that come with X-Plane if possible, so that I can duplicate the bug.
Once again, be sure to:
- 1. Use a checklist to explain what you are doing, starting with deleting the preferences.
- 2. Include every step in the checklist that you send in your bug report.
- 3. Use proper terminology. If you do not know the name of an instrument, then go into Plane-Maker and click on it with the mouse. The X-Plane instrument name will be displayed at right. Or turn on the “Show Instrument Descriptions” option in the Special menu of X-Plane to get the real name of the instrument that you think is wrong.
- 4. Explain why you think the result you are seeing is wrong. Provide proof if you think the sim is not doing what the real plane would do.
Remember, a bad report would say, "The pressure gauge does not work." (What pressure gauge? Why do you think it does not work? What do you expect it to show? What plane are you even flying?)
A good report would say, "On a Mac running OS X, I deleted the preferences and opened the following plane with the File menu, then I set the controls as follows, then I observed the manifold pressure gauge to indicate manifold pressure of zero as I advanced the power, though in the real plane I would get 25" of manifold pressure in this plane, as I know from the following excerpt from that plane's pilot’s operating handbook."
That report indicates what type of computer you are using, what you do to get the problem (in a way that lets me perfectly mirror it), what you think the problem is, and it gives proof that what you believe about the plane is in fact true. That is enough info for me to work with!
Also, send the log.txt file! This lists what type of computer you have. Hardly anyone even thinks to mention whether they are on Mac, Windows, or Linux!