Nav Loading...
 

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 few 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 the software? Is there a git identifier for the version number?
  • If it's an OpenBSD problem, what version of the kernel and userland are you running: CD-ROM 5.X? Stable or Current/Snapshot?

If it's a Java Compilation problem:

  • What file(s) you tried to compile? Did you change the source file or the Maven build file in any way?
  • Are you compiling it under Eclipse or with Maven?
  • 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 the JavaSE SDK, 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. And will not get a response.

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 systems with command-line capabilities, you can use "redirection" to capture a log of program output. On developer-friendly systems (UNIX/Linux/Mac OS X) you can use 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 textual log of results from 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 or bugfix to my software, please send it as a "git pull request" for the repos on https://GitHub.com/IanDarwin/, or send it as a diff(1) -u output. 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! And by the way, please do not ever write in asking me for links to files that are on my public web site. You should instead learn to find stuff on your own instead of expecting others to spend their time doing it for you, for free. If this is a consulting gig, that's great; I live in Canada and I charge North American consulting rates.


Similar: Sun's notes on How to Write a Helpful Bug Report, Simon Tatham (author of putty ssh client) on How to Report Bugs, and Eric Raymond's Asking Smart Questions.