| |
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.
Dont be afraid -
Smalltalk in general is pretty robust.
That means, that bugs usually
only have local effects. That means, 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.
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).
There might be codeGenerator bugs and even be 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 in the debugger),
or abort the operation.
A bug is proceedable, if it happened in some notifyer, message output function or draw
function.
You should abort, if the first 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 functions result.
In some rare situations, the application in which the error occurred is corrupt (du 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 dont write a snapshot of an already corrupted image.
The snapshot save utility keeps the previous snapshot image as "st.bak" around, which
is occasionally helpful (to start st/x with this backup-snapshot, enter "smalltalk -i st.bak").
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:
- 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...
- ST/X version
no comment - thats obvious.
- 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.
- 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.
- 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).
- 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").
Summary
Dont fear the bug - they are part of a humans life !
Doc $Revision: 1.3 $