How to Report a Bug

There are some important things to know about reporting bugs. Proper bug reporting is critical to getting the application bug free (or as near to it as is reasonably possible).

Why report bugs?

Surely the person who is developing the application is aware of all the bugs? After all, isn't he responsible for all the code?

In a perfect world this would be the case. However, it's not a perfect world. The application is an extremely complex beast with many parts that interact with one another. The bugs often occur in those interactions. For the developer to be aware of all bugs, he would have to test every possible interaction with every possible input data value, on all platforms, with all operating systems, etc.. This is not feasible. Hence, you will find bugs that have never been seen before. It's important that the developer is made aware of those problems so that they can be fixed.

What is a bug?

A bug can be any of the following (typically in descending order of nastiness):

• A crashing bug that causes the application to quit unexpectedly.
• An unhandled exception. These are error conditions that are not being handled by the application code, but should be.
• Bad results (e.g. an altitude reported as 95°, an RA of -2.5 hours, 12 items reported deleted when only 11 are in the list, etc.). These do not cause a crash or exception, but are nonetheless incorrect.
• Unexpected side-effects. (e.g. when you open a preferences window another window is resized, etc.)
• Cosmetic problems (e.g. overlapping text, controls that are not redrawn properly, incorrect tabbing order, spelling typos, flickering controls,etc.). These do not affect the operation of the application, but are annoying or irritating.
• Documentation problems (e.g. diagram in manual does not correspond with the actual application, etc.).

When to report bugs

As soon as any bug appears, it should be reported, unless you have already done so for the exact same bug and don't have anything different to say about it. That is the case for any of the above bug types. Anything you consider an anomaly is probably a bug and should be reported. Just because you can work around a bug does not mean it is not worth reporting.

Even if you do something completely outrageous, like pasting the entire works of Shakespeare into an object's Notes field, or making 20,000 observations of NGC1234, it should not cause an exception or any other kind of bug, but should fail with a suitable error message or warning. If a bug does occur - report it.

How to report bugs

How you report bugs is important. Here is a list of ways to report bugs, with the best and "most likely to succeed" methods first.

• Use the Report a Bug... feature in the Help menu of AstroPlanner V2. This ensures the bug goes directly into the bug database and is attended to as soon as possible. You can find a list of outstanding bugs in the database here. You'll need a live Internet connection to report via this method.
• If an exception occurs you will (most of the time) be presented with an exception reporting window, which should be used to report the exception. You'll need a live Internet connection to report via this method.
• Send an email to support@astroplanner.net, detailing the bug and attaching any error logs, screenshots, plan documents causing the problem, etc.
• Send an email to the beta mailing list (which you should be a member of). This is the preferred method only if you're not sure if something is a bug or perhaps is a misunderstood feature. Someone is sure to help put it in the correct category.
• Post a message to to the AstroPlanner groups.io Group. You should only resort to this if your e-mail is malfunctioning, since it's likely to annoy group members who don't care about bugs in beta releases.

What to include in a bug report

The quality of your bug report is critical to getting the bug fixed. A good report should include the following (where applicable):

• The version of the application you are testing (e.g. 2.0.1b5).
• The platform and operating system you are using (e.g. Windows 7 SP1 64-bit, Mac OS X 10.7.2)
• What you were doing when the bug occurred. Please try and use correct terminology to make your description more understandable. (e.g. Bad: "the eyepiece picture isn't always there" vs. Good: "The chart on the Field of View tab often doesn't redraw properly when you first select that tab").
• Whether you are able to reproduce to bug when you tried a second time. Reproducible bugs are much easier to find and fix.
• Any error messages reported.
• Attach any error log files from your desktop.
• Attach screen shots (images) showing the bug occurring, if possible. This is really important and useful for the developer, especially if English is not your first language. Remember that "a picture is worth a thousand words." I have fixed many bugs almost instantly based on a screenshot, where the user has struggled to describe the problem adequately in words.
• If you wish, you can attach copies of the plan document your were working on when the bug occurred.