Subject: What to include in a bug report
To: None <>
From: J.T. Conklin <>
List: current-users
Date: 06/17/1994 21:56:19
While I'm cleaning up the "What is GNATS and how do I use it" document
which I post periodically, I thought I'd submit this list of things a 
good bug report should include.

(I culled this from the send-pr texinfo documentation)


In general, common sense (assuming such an animal exists) dictates the
kind of information that would be most helpful in tracking down and
resolving problems in software.

* Include anything *you* would want to know if you were looking
  at the report from the other end.  There's no need to include every
  minute detail about your environment, although anything that might
  be different from someone else's environment should be included
  (your path, for instance).

* Narratives are often useful, given a certain degree of restraint.
  If a person responsible for a bug can see that A was executed, and
  then B and then C, knowing that sequence of events might trigger the
  realization of an intermediate step that was missing, or an extra
  step that might have changed the environment enough to cause a
  visible problem.  Again, restraint is always in order (``I set the
  build running, went to get a cup of coffee (Columbian, cream but no
  sugar), talked to Sheila on the phone, and then THIS happened...'')
  but be sure to include anything relevant.

* Richard Stallman writes, ``The fundamental principle of reporting
  bugs usefully is this: **report all the facts**.  If you are not
  sure whether to state a fact or leave it out, state it!''  This holds
  true across all problem reporting systems, for computer software or
  social injustice or motorcycle maintenance.  It is especially
  important in the software field due to the major differences seemingly
  insignificant changes can make (a changed variable, a missing
  semicolon, etc.).

* Submit only *one* problem with each Problem Report.  If you have
  multiple problems, use multiple PRs.  This aids in tracking each
  problem and also in analyzing the problems associated with a given

* It never hurts to do a little research to find out if the bug you've
  found has already been reported.  Most software releases contain
  lists of known bugs in the Release Notes which come with the
  software; see your system administrator if you don't have a copy of

* The more closely a PR adheres to the standard format, the less
  interaction is required by a database administrator to route the
  information to the proper place.  Keep in mind that anything that
  requires human interaction also requires time that might be better
  spent in actually fixing the problem.  It is therefore in everyone's
  best interest that the information contained in a PR be as correct
  as possible (in both format and content) at the time of submission.