Reporting a Software Problem

When reporting any software problem (to me or to anybody else), you need to include the following in in your report:

• What you did...
• What you saw...
• What you think the problem might be...

What you did

What version of the software are you using. Be specific:

• If it's a web site problem, when did it occur? What are the last 3 URLs you visited on the site? Does it happen repeatedly or did it just happen once?
• If it's a Java Cookbook problem, what day of what month did you you download it? Is there a version identifier in the file? Use ident to find it, or look for the string beginning with a dollar sign and "Id".
• If it's an OpenBSD problem, what version of the kernel and userland are you running: CD-ROM 3.X? Current Snapshot? Current built from sources?

If it's a Java Compilation problem:

• What file(s) you tried to compile? Did you change the file in any way?
• The exact command you used to compile it, including computer output showing what your CLASSPATH is actually set to at compile time.
• What version of the compiler? If you are using Sun's JDK/JSDK, the exact output of "javac".

If it's a Java runtime problem:

• Your classpath
• The command used to invoke it.
• The exact output, including the stack trace. See below.

What you saw

Just saying "it won't compile" or "it didn't work" is not useful. Doing this has been known to reduce the bravest, most patient developer to alternating fits of rage and tears. Please don't do this.

In all cases, please send the exact and complete output from the browser or the compiler or the runtime.

For web site problems, copy and paste the whole error mess from the browser into your mail program; don't just type one or two words from the screen.

On UNIX systems you can use redirection, or the script(1) program to capture a log of the errors. On other systems, or if you're using an Integrated Development Environment, you should be able to grab the results off your screen using copy and paste.

For Java programs, you should ensure that the code prints a stack trace if it catches any exceptions. See Java Cookbook Section 1.6, many code examples such as the code in Section 5.1, and Section 9.6 for capturing tracebacks from others' code.

What you think

If you have a theory, please include it (but mark it as such :-)).

If you want to send an update, please send it as a diff(1) -u output, preferably against the current cvs version. Thank you!

Results

These steps will help you get a useful response. Depending on your support arrangements I will try to get back to you as soon as I can, but remember that free software that you aren't paying support on is a second priority to work that pays the bills!

See also Sun's notes on How to Write a Helpful Bug Report and Eric Raymond's Asking Smart Questions.

DarwinSys - Java Cookbook - Contact Form