Reporting bugs

Sometimes software crashes and you end up with an obscure-looking error message on the screen. This page is a brief guide on how to attempt to grab some pertinent debugging information which can be used in order to help find and fix the bug.

Classifications

Software might have different classes of defects, some more serious than others.

Behaviour doesn’t match documentation

That may imply that the documentation is out of date, or that the implementation of the software is incorrect.

Non fatal errors

Perhaps a dialogue box silently closes without warning, or a few pixels get corrupted on the screen. These most likely are bugs, but their side effects appear harmless and are tolerable.

A serious error

Common serious error messages tend to result in an error box with a cryptic message such as

along with some other numbers or odd looking stuff in them. Telling the software author just the first bit really won’t help them to fix the bug; they need the whole message.

Capturing the bug

Your first step is to try to get the bug so that you can roughly repeat it. Once you’ve managed that, you should know the rough sequence of events that you go through before it happens.

What leads up to the crash?

This is sounds easier than it is, of course. Some bugs are obscure and you only see them the once and others seem to happen at random intervals. Your only hope of debugging those types of bug is to be prepared in advance – as explained below.

If you can repeat a crash through some sequence of actions, that sequence is usually of great importance to the software author so will be among the first useful bits of information you can give them.

Being ready for a crash

Make sure your system has a copy of the *Where command. If your version of the OS has version 1.90 or later of the Debugger module then the command will be built in. If not, you can use the Where utility from The ARM Club (which you would normally install in !Boot.Library), or you can use the version provided by the DebugTools module (available in the Bonus Binaries download)

The DebugButton module (also available in the Bonus Binaries download) can also be useful, to allow you to get straight to a Debugger prompt from some error boxes.

When the crash happens

If a crash leads to an error box which says “Describe”, “Quit” or “Continue” you should click on the “Describe” button. A new error box will appear – make a note (on paper) of the full error message.

If a crash leads to one of the ‘serious’ error messages, open a command prompt (either in a task window Ctrl-F12 or single tasking at the bottom of the screen with F12) and type the following sequence of commands:

If you have the DebugButton module loaded then you can often get straight to a command prompt by pressing the “Debug” button in the error box. Try and use this method if possible, as it will produce more accurate results, especially when crashes occur in application space.

Depending on the type of crash, the two *MemoryI commands may produce some errors. Don’t worry, that’s fine; the other information in the crash report will still be useful.

For an application that has crashed look in the ‘About this program’ box. The author will need to know which version you were using in order to help.

Sending the report to the author

Locate the ‘capture’ file in the root directory ready to send off, it’s just a text file, you can view its contents in your favourite text editor.

Bugs in 3rd party software

In the first instance, you should contact the application author directly, including the ‘capture’ file alongside the version number of the application in use, and any serial number or similar to illustrate your eligibility for support.

Be sure to describe the events surrounding the crash, as detailed in ‘Capturing the bug’ earlier.

If the version of software you have is out of date the bug may already be known about and have been fixed. Sometimes there’s a charge for new versions to cover development time, support the author by making sure you’re up to date.

It may also turn out the application isn’t at fault, and a bug in the operating system has caused it to malfunction. The application author should be able to quickly identify if that is the case or not based on other operating system versions they might use.

Bugs in ROOL hosted software

Be aware that the nightly builds should be considered of beta quality. ROOL does zero testing on these – they come from a server that runs when everybody is asleep.

First, log in to your account on this site. You need to register an account with our web site (see the “Log in” link top-right) so that we know who reported which bugs.

There are two ways to propose that you’ve found a bug:

• If you’re a little uncertain about what you’re seeing, or want to ask if others have the same problem with their setup, the bug forum is the best place to start. Search the recent topics to see if others in the community are discussing the same thing, or create a new topic if searching yields nothing.
• If you’re happy that the indications all point to a bug and don’t have anything to ask the community, the bug database can be used instead. Search the closed bugs to see if others have already spotted the same thing, or open a new ticket if searching yields nothing.

For both the bug forum and the bug database, describe the steps you performed leading up to the crash, what information you captured (such as the ‘capture’ file described above) when it went wrong, just as you would for a 3rd party application.

Bear in mind that there are several hundred pieces of software hosted by ROOL, so getting a bug fixed might require some more effort on your part

• If the problem is because of a recent change, there’s a good chance it’ll be fixed promptly while the programmer responsible can still remember how it all works.
• If the problem is in a rarely touched corner then you may have to proactively seek a fixer to help resolve it. You need to pitch the bug to the group of people who
  • Can recreate the bug in their setup
  • Are interested in helping
  • Are capable of fixing the problem
  • Have some spare time to look into it
• If the problem is complex or reliant on fixes in secondary or tertiary bits of code then you may have to wait until those pieces of the jigsaw have been finished first, while that might mean waiting longer to have the bug tended to it’s better than papering over the crack only to have the crack re-appear when the foundations move.

Remember, the ‘fixer’ might be the same person who wrote the software in the first place – so don’t be rude in your bug report – you want them to help you!

Summary

As illustrated here, collecting good information about a defect you have seen is just as important as changing the source code.

Thanks for your help!