Helpful hints

f78 Helpful hints

Helpful hints

There is no orthodox standard for submitting effective bug reports, though you might do well to consult the documentation on submitting bugs for gcc in Reporting Bugs in Using GNU CC in GNUPro Compiler Tools.

The following documentation contains instructions on what kinds of information to include and what kinds of mistakes to avoid.

In general, common sense 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 (unique paths, for instance).
Narratives are often useful, given a certain degree of restraint. If Cygnus Solutions support staff 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, be sure to include anything relevant and pertinent and remember restraint is always in order (comments such as “I set the build running, went to get a cup of coffee...Columbian, cream, no sugar...talked to Sheila on the phone, and then THIS happened...” is not exemplary of restraint and “THIS” is not relating critical circumstances pertinent to the problem unless, of course, Sheila spilled coffee on your system).
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 program.

It never hurts to do a little research to find out if the bug you’ve found has already been reported. A list of known bugs is documented in Problems Fixed in This Release in Release Notes for GNUPro Tookit; see your system administrator if you don’t have a copy of this documentation.

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.