12.4. Who Do I Turn to?

No matter how good something is or how much documentation comes with it, you'll eventually come across something that you don't understand or that doesn't work. In such cases it can't be stressed enough to carefully read the documentation (in computer parlance: RTFM).^[3] In many cases this will answer your question or point out what you're doing wrong.

^[3] RTFM stands for "Read The F(laming) Manual."

Sometimes you'll find this only adds to your confusion or confirms that there is something wrong with the software. The next thing to do is to talk to a local bash guru to sort out the problem. If that fails, or there is no guru, you'll have to turn to other means (currently only via the Internet).

12.4.1. Asking Questions

If you have any questions about bash, there are currently two ways to go about getting them answered. You can email questions to bash-maintainers@gnu.org or you can post your question to the USENET newsgroups gnu.bash.bug or comp.unix.shell.

In both cases either the bash maintainer or some knowledgeable person on USENET will give you advice. When asking a question, try to give a meaningful summary of your question in the subject line.

12.4.2. Reporting Bugs

Bug reports should be sent to bug-bash@gnu.org, and include the version of bash and the operating system it is running on, the compiler used to compile bash, a description of the problem, a description of how the problem was produced, and, if possible, a fix for the problem. The best way to do this is with the bashbug script, installed with bash.

Before you run bashbug, make sure you've set your EDITOR environment variable to your favorite editor and have exported it (bashbug defaults to emacs, which may not be installed on your system). When you execute bashbug it will enter the editor with a partially blank report form. Some of the information (bash version, operating system version, etc.) will have been filled in automatically. We'll take a brief look at the form, but most of it is self-explanatory.

The From: field should be filled out with your email address. For example:

From: confused@wonderland.oreilly.com

Next comes the Subject: field; make an effort to fill it out, as this makes it easier for the maintainers when they need to look up your submission. Just replace the line surrounded by square brackets with a meaningful summary of the problem.

The next few lines are a description of the system and should not be touched. Next comes the Description: field. You should provide a detailed description of the problem and how it differs from what is expected. Try to be as specific and concise as possible when describing the problem.

The Repeat-By: field is where you describe how you generated the problem; if necessary, list the exact keystrokes you used. Sometimes you won't be able to reproduce the problem yourself, but you should still fill out this field with the events leading up to the problem. Attempt to reduce the problem to the smallest possible form. For example, if it was a large shell script, try to isolate the section that produced the problem and include only that in your report.

Lastly, the Fix: field is where you can provide the necessary patch to fix the problem if you've investigated it and found out what was going wrong. If you have no idea what caused the problem, just leave the field blank.

Once you've finished filling in the form, save it and exit your editor. The form will automatically be sent to the maintainers.