Copyright © 2018-2021,2022 by Thomas E. Dickey
A good bug report will give me enough information that I can see the same problem that you see. Once I can see it, and repeat the conditions which show the bug, I can narrow it down to find the cause.
Not all computers are the same. I want to know which system in case I am able to run the program on a comparable machine. That includes
Since the mid-1990s, my programs use autoconf configuration scripts with a number of options. If you are using a package for one of my programs, I will find the options used by the packager. If you are compiling it yourself, I will need the same information. In this case, I would also like to see
config.log file generated by the
config.status file generated by the
messages printed by the configure script
messages printed by the
Unless you are demonstrating a problem with parallel
make, turn the corresponding option (e.g.,
Use attachments (a standard feature of email since the late 1990s) and avoid using HTML-mail, if you really want people to read your report.
Verify if the bug has been fixed in current development. If you found a problem in a packaged version, it may have been fixed (sometimes, this may be a few years ago).
Identifying the configuration is the first step toward verifying if the bug has been fixed.
If you have found a bug in an older version, that may be important to the packagers, e.g., to alert them to the need for updating the package, or to apply a patch.
If the problem did not lie in configuring or building the program, then you must be able to run it. A script or small test-program which demonstrates the problem is valuable. Others have elaborated on the topic (though it is fair to point out that these are relatively recent episodes in a long story):
How to create a Minimal, Complete, and Verifiable example (MCVE)
Short, Self Contained, Correct (Compilable), Example (SSCCE)
I may already have a test-case. For example:
Non-interactive programs have sets of test-data, e.g., byacc, cproto, diffstat. Testing interactive programs is not so straightforward.
I test xterm and ncurses with vttest, tack as well as ncurses-examples.
Some custom scripts are bundled with xterm in the
I have other scripts and programs, either custom or part of bug-reports.
Some of the programs have compile-time or run-time options for debugging traces, including xterm, ncurses, lynx, and vile.
If an example is interesting enough, I add or adapt it to my collection.
Some people offer to send the core file generated when a program dies unexpectedly. I have received unsolicited core dumps as part of a problem report (sometimes not even as an attachment, but pasted into the message).
I delete the core dumps, finding them not useful. Instead, a traceback using a debugger is often helpful:
# myprogram Segmentation fault (core dumped) # gdb myprogram core (gdb) tb #0 0x00007f868d718337 in kill () at ../sysdeps/unix/syscall-template.S:81 #1 0x000055f0d8442a1f in mch_exit () #2 <signal handler called> #3 0x00007f868d7c4893 in select () at ../sysdeps/unix/syscall-template.S:81 #4 0x000055f0d8443f63 in ?? () #5 0x000055f0d8444433 in ?? () #6 0x000055f0d84446bb in mch_inchar () #7 0x000055f0d84c39f8 in ui_inchar () #8 0x000055f0d83d329f in inchar () #9 0x000055f0d83d534e in ?? () #10 0x000055f0d83d5b13 in vgetc () #11 0x000055f0d83d5f89 in safe_vgetc () #12 0x000055f0d842461f in normal_cmd () #13 0x000055f0d850896d in main_loop () #14 0x000055f0d834a2e1 in main () (gdb) quit #
A traceback using a debugger is often useful, but not always:
the core file may be truncated due to process limits (and the traceback is useless), or
the core file may be for a different program than you
suppose. Use the
file program to check which
program dumped core. If I see a traceback which does not show
the main entrypoint, I know immediately that it is
the traceback may show interesting function-names, but it really helps to have line-numbers to show where the problem may lie.
If you have compiled my program, then the bug report's traceback should show line-numbers for a debug-executable. Prepackaged programs are a different matter altogether (there will be no line-numbers). Given the distributor, package version, I may investigate by compiling that configuration.
Suggested improvements should be sent as a source patch:
Explain the problem that you are fixing.
Please use "
diff -u" format (unified), even
if you are creating a new file. Otherwise I may overlook it,
if it is at the end of a long patch. (It is reasonable to
send binary files in uuencoded form (or the MIME equivalent),
but there are few of those).
If it is neither a unified or context diff, I may simply ignore it.
Don't send patches that include the
configure” script if the difference
therein can be regenerated using
While I will consider patches which make some useful feature more configurable, I generally disregard patches which change the default configuration.
Do specify the version of the program which you are fixing. All of my programs have versions, with either a patch number or a patch date.
Problems due to packagers' modifications should be directed to their respective bug-tracking systems.
Until 2010, most of my development (aside from $dayjob) was on PCs using a multiboot configuration. At one point I had more than 80 systems set up in this way. Since 2010, I have used mostly virtual systems with different tools, and increased the number of systems somewhat. I also have had development access to a number of Unix systems for quite a while, but none of that is under my control.
If the system you are using is not something that I can set up in a virtual machine, there is little (aside from advice) that I can offer for support.
Given those considerations, these operating systems are defunct:
Apollo, CLIX, IRIX, IRIX64, OSF/1, Tru64,
OS/2 EMX environment, BeOS, QNX,
Windows before 7 (2003, 2000, NT, 98, 95, 3.1),
These versions of Unix operating systems also are defunct:
AIX 4 and before,
HPUX 10 and before,
Solaris 9 and before,
SunOS 4 and before.
Some viable systems may have users, but if I have no access, I cannot support programs. My experience with no-access guarantees that I'll only accept trivial build-fixes. There is no point in having features in a program that I cannot test.
BeOS survives, more or less as Haiku. I can build and test programs with that system.
OS/2 lingers on as eCOMStation. Around 2010 I set up a development system with Parallels, which died due to an upgrade. But it works with VirtualBox and possibly VMware.
Until 2008, I was able to use VMS in the HP test-drive. That went away. Some people have reported success with simh. Perhaps sometime I will too.
I occasionally see bug reports for Gentoo, but my involvement with those is limited to advice and comparison with other systems. Gentoo (like Linux From Scratch) assumes that the user compiles everything. No one has time for that, unless it is the only system they use.
Most of the reports which I get through a bug tracking system are via Debian; the Redhat system is a distant second. Systems derived from Debian (in particular, Ubuntu) which contribute very little to my projects fall at the other end of the spectrum. If you want to report a bug in one of the Debian-derived systems, you are best advised to open a bug report in the Debian bug reporting system.
While the MCVE/SSCCE pages are interesting, Usenet FAQs used to give similar information during the 1980s/1990s. These pages for instance were written by others based on that environment: