== Reporting bugs ==
If you find a bug in the Linux kernel, you should notify the kernel developers of it as soon as reasonably possible. There are at least two important reasons to do this. First, the configuration of your system may be unique and you may be the only person seeing this particular problem. In that case, if you do not report it, then most likely the next versions of the kernel will not work properly on your computer. Second, the problem observed by you may be related to some other issues being investigated by the kernel developers and by reporting it you may provide them with a valuable data point.

You should not be afraid of reporting known bugs. At worst, if you report one, someone will tell you that it is known. However, if the problem is related to hardware, your report may contain the additional information needed to identify the source of it. For this reason, it generally is also a good idea to confirm problems reported by other people, if you are observing them too.

In general, the kernel developers’ preferred way of reporting bugs is email, because it allows them to react quickly to the problems that are easy to fix. Still, later on, if the reported problem turns out to be difficult, you may be asked to open an entry in the Linux kernel bug tracking system at http://bugzilla.kernel.org. Usually, this requires you to do some more work than just sending an email message with a bug report, but it often is necessary to collect all information related to the reported bug in one place, so that it is easily accessible at any time.

Email messages containing bug reports should generally be sent to the Linux Kernel Mailing List (LKML) or to the mailing list dedicated to the affected subsystem. You may send bug reports to two or three mailing lists simultaneously, but if you send them to more than three lists at a time, people will likely get angry with you.

It also is a good idea to notify the maintainer of the affected subsystem and the maintainer of the tree in which the bug is present (e.g. Andrew Morton, if the bug appears in the -mm tree) by adding their email addresses to the CC list of the bug report message. The email addresses of maintainers of the majority of kernel subsystems can be found in the MAINTAINERS file in the root of the kernel source tree.

If you know which patch has caused the problem to appear, you should also add the email address of its author to the CC list of your bug report (this address is usually present in the ’From:’ field of the patch header). Additionally, it is recommended to notify all of the people involved in the process of merging the patch (you can find their addresses in the ’{{{Signed-off-by:}}}’, '{{{Reviewed-by:}}}', and ’{{{Acked-by:}}}’ fields of the patch header). This way you can increase the probability that someone ”in the know” will notice the report and respond to it quickly. Apart from this, you should make it clear that your message contains a bug report, for example by adding the word ”BUG” in front of the message’s subject line.

Nevertheless, sometimes bug reports are not responded to even if they contain all of the right email addresses etc. If that happens to your bug report, you should first check if it has not been intercepted by a spam filter. This is easy if you have sent the report to a mailing list, since in that case it only is necessary to look into the list’s archives to see if the message is there. If it turns out that the report has reached the list and no one is responding to it, the developers might have overlooked it or they are too busy to take care of it right now. In that case you should wait for some time (usually, a couple of days) and send it once again (if you resend the report, you may add the word ”resend” to the message’s subject to indicate that this is not the first time). If that does not help and there still is no response, it is best to open a new entry in the bug tracking system at http://bugzilla.kernel.org .

As far as the contents of bug reports are concerned, you should generally avoid putting irrelevant information into them. Of course, that may be difficult, because you may not know which information is relevant in given particular case. Still, you can always safely assume that if more information is needed, the kernel developers will ask you to provide it.

First of all you need to say what the bug is, which kernel version it is present in and how to reproduce it. You also need to describe the symptoms and include all of the corresponding kernel messages, if you can collect them (see Chapter 3). In particular, the following things should be present in a good bug report:
 * description of the reported problem,
 * version of the kernel in which the problem appears,
 * the last known version of the kernel in which the problem does not appear (if applicable),
 * architecture of the system on which the problem is observed (that may include some more detailed hardware information if the problem seems to be hardware-related),
 * steps to reproduce the problem,
 * kernel messages related to the problem (if available).
Additionally, if you know which patch has introduced the problem, the name of it or the identifier of its commit should also be included in the report. You can refer to the file Documenation/admin-guide/reporting-bugs.rst (or reporting-issues.rst) in the kernel source tree for more information about the reporting of bugs.

After reporting a bug you may be provided with a patch to test. In that case you ought to test it and report back to the developer who have sent it to you whether or not it fixes the bug. If it does not fix the bug, you will likely receive more patches to test. Otherwise, it is polite to thank the developer for his work.

The preparation of bug reports may be automated with the help of ORT. After running it:

{{{$ ./ort.sh oops.txt}}}

(oops.txt is a file with some scary kernel messages) you will need to specify the report type:
 * short – basic information only
 * custom – user-defined report contents
 * template – report from a template
Next, you need to type in the required information and choose the options that you want. The report is then generated according to the template included in the reporting-bugs.rst file.

The newest version of ORT is available at http://www.stardust.webpages.pl/files/tools/ort/ . If you use it, be careful not to generate reports containing too much irrelevant information, which unfortunately is quite easy to do with the help of this tool.