[up]
To err is human.
We are human.

How to Report Errors

This page is meant to give you a guideline on what should be done when an error happens and how they should be reported to others.

Introduction

Sooner or later, you will probably encounter a bug somewhere. Don't be afraid - Smalltalk in general is pretty robust. That means, that bugs usually only have local effects (i.e. that if some functionality in an application has a defect, other parts of the system and usually also other parts of the buggy applications are not affected, and continue to function).

What kind of bugs typically occurr ?

From our experience, most bugs are "UndefinedObject does not understand"-kind of bugs. That means, that at some point in the program, a variable was not initialized and, as a consequence, a followup message was not understood.

Another class of bugs is related to assuming that something is in a container, which is not. I.e. when accessing a dictionary ("no such element"-bug) or when removing from an already empty container.

A bit more subtle are index bugs - often resulting from a previous search, which failed to find an element (and the bad index which is usually 0 is then used).

Although more seldom, but still occasionally happening are FileNotFound exceptions, typically occuring with file open operations.

There could even still be codeGenerator bugs in the compiler and even crashes of the support system (Virtual Machine).
But, luckily, these are relatively rare.

Interestingly, wrong type errors (i.e. sending a message to some object which it does not implement) are actually very rare (except for the UndefinedObject case above).
This is in contrast to what many advocates of static typed languages promote.

What should I do when a debugger opens up ?

In most situations (>>90%), the bug does not affect other parts of the system, and it is still usable after you either ignore the bug (proceed/continue in the debugger), or abort the operation (click on the "Abort"-Button in the debugger).

A bug is proceedable, if it occurred in some notifier, message output, or draw function.

You should abort, if the bug produces followup errors, due to missing intermediate values.
Remember, that the "abort" action in the debugger brings you right back into an applications main event handling loop - whatever action it was currently executing, will be aborted.
That means: if it was performing a menu action, that menu action is aborted; if it was handling a keyStroke, that processing is aborted; and if it was doing a redraw, the redraw will be aborted.

Of course, whatever function it was performing will not be completed and you will see a partially drawn window, or a partially performed menu-function's result.
If the error happened during a file-write operation, that file may now be incomplete and contain garbage - be careful to not loose any data (most of the write operations in the ST/X system are aware of possible errors and will keep a backup version of a file which is being overwritten).

In some (rare) situations, the application in which the error occurred is corrupt (due to some internal state, which is now bad) and errors continue to pop up.
In that case, you should try to save any modified data and close that window (not ST/X as a whole), reopen the application and try again.

In very rare situations, the whole system is corrupted and the only chance is to restart ST/X from the last snapshot. Thus it is useful to save snapshots from time to time. However, be sure that you don't write a snapshot of an already corrupted image over your previous (good) image file. A good strategy is to use names such as "stN.img", with N counted up. When you are certain that the state saved in "stN.img" was a good one, you can ocasionally remove older snapshots. (to start ST/X with one of your previous snapshots, enter "smalltalk -i stN.img".)
The snapshot save utility keeps the previous snapshot image as "st.bak" around, which is sometimes helpful (to start ST/X with this backup-snapshot, enter "smalltalk -i st.bak").

What if I have no good snapshot image file at all ?

If all of the previous snapshot files (if any) got corrupted, or you deleted them by accident, you can still restart from scratch (i.e. without a snapshot) eihter by deleting "st.img" and then starting ST/X, or by telling ST/X to ignore the image with the -I flag as in "stx -I".
Of course, all of your changes will not be present initially; however, after opening a Changes Browser and re-applying all of you changes individually. Make sure to skip or stop before the change which was responsible for the crash (if it was one of your changes).

Can I fix an error myself ?

Of course you can - and you are welcome to do so !

Smalltalk systems are meant to be used, modified and adjusted. As opposed to closed systems, where you MUST call for and wait for bug fixes, Smalltalk is open and you are free to change things, and fix bugs right away.

How should I report an error ?

Of course, whether you fix a bug or not, it is useful and fair if you let others know about it, any possible workarounds and (if possible) even fixes, patches etc.

However, in order for us to be able to handle bug reports efficiently, we would like to ask you to include the following information in all bug reports:

  1. Platform
    That is the machine type, OperatingSystem-brand and OS-version.
    The reason is that often errors only happen in certain environments and are hard to reproduce on other systems. Especially, Windows systems often behave quite different from Unix systems...

  2. ST/X version
    no comment - thats obvious.

  3. Description
    Information like "the system crashes", "it does not come up" "it compiles wrong" etc. are obviously not very helpful.
    The bug should be described in as much detail as possible.

  4. Scenario
    This is probably the most useful information: how did you get the error, and how can it be reproduced. If a bug cannot be reproduced, it is *VERY* difficult for us to fix it.

  5. ST/X state information
    A *VERY* useful piece of information is the debuggers stack-backtrace, and it should be included in a bug report.
    To support this, the debugger provides two menu functions: "copy walkback stack" and "mail report".
    The first copies the walkback text into the clipboard, for inclusion into a bug report.
    The later provides a bug report template (including the walkback), and offers to send a report to us (eXept).

  6. BugFix
    If you have a fix, please go ahead and publish it. The best form is as a patch in Smalltalk code-chunk format. This is the format in which the changes file is written. Individual patches are created either in the browser ("fileOutAs" of an individual method), or in the changes browser ("save change as").
Starting with Summer 2004, there is a central service for ST/X bug tracking, based upon the Bugzilla bugtracking tool. Please report any bug via the webservice at: "http://bugs.exept.de".

Summary

Don't fear the bug - they are part of a humans life !


[stx-logo]
Copyright © 2003 eXept Software AG, all rights reserved

<info@exept.de>

Doc $Revision: 1.12 $ $Date: 2009/09/21 13:52:21 $