Make it obvious that bugzilla.kernel.org most of the time is the wrong place to file a report, as it's not working well. Instead, tell users how to read the MAINTAINERS file to find the proper place for their report. Also mention ./scripts/get_maintainer.pl. Sadly this is only available for users that have the sourced at hand; in an ideal world somebody would build a web-service around of this. Signed-off-by: Thorsten Leemhuis --- = RFC = This section tells users to always CC LKML. I placed this in the text here for now as a way to force a general discussion about this, as it would be way easier if users had one place where they could search for existing reports; maybe it should be the same place where fixes are sent to, as then the single search would find those, too. That might mean "LKML", which these days afaics is a kind of "catch-all" ml anyway (which nearly nobody reads). So it might make sense to go "all in" and make people send their reports here, too. But TBH I'm a bit unsure myself if that's the right approach. Maybe creating a mailing list like 'linux-issues@vger.kernel.org' would be best (and while at it maybe also linux-regressions@vger.kernel.org). --- Documentation/admin-guide/reporting-bugs.rst | 166 ++++++++++++++----- 1 file changed, 121 insertions(+), 45 deletions(-) diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst index 61b6592ddf74..3e9923c9650e 100644 --- a/Documentation/admin-guide/reporting-bugs.rst +++ b/Documentation/admin-guide/reporting-bugs.rst @@ -370,6 +370,127 @@ from being loaded by specifying ``foo.blacklist=1`` as kernel parameter (replace 'foo' with the name of the module in question). +Locate kernel area that causes the issue +---------------------------------------- + + *Locate the driver or kernel subsystem that seems to be causing the issue. + Find out how and where its developers expect reports. Note: most of the time + this won't be bugzilla.kernel.org, as issues typically need to be sent by + mail to a maintainer and a public mailing list.* + +It's crucial to send your report to the right people, as the Linux kernel is big +project and most of its developers are only familiar with a very small part of +it. Quite a few developers only care for just one driver; some of them also look +after the various infrastructure building blocks the driver is building upon, +but sometimes other maintainers take care of those. These people talk with each +other, but work mostly separately from each other. But most of them don't care +about file systems or memory management, which yet other people take care of. + +Problem is: the Linux kernel lacks a central bug tracker that all maintainers +use, so you have to find the right way and place to report issues yourself. One +way to do that: look at the `MAINTAINERS file in the Linux kernel sources +`_, +which lists the points of contact for the various parts of the kernel. The file +contains a long text with sections that among others will mention who maintains +the various parts of the kernel and the development mailing list for that code. + +How to decode the maintainers file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To illustrate how to use the file lets assume the Wi-Fi in your Laptop suddenly +misbehaves after updating the kernel. In that case it's likely an issue in the +Wi-Fi driver; it could also be some code it builds upon: the Wi-Fi subsystem, +the TCP/IP stack, which are all part of the Network subsystem. But unless you +suspect the culprit lies there stick to the driver. Thus run the command +``lspci -k`` to tell which kernel driver manages a particular hardware:: + + [user@something ~]$ lspci -k + [...] + 3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32) + Subsystem: Bigfoot Networks, Inc. Device 1535 + Kernel driver in use: ath10k_pci + Kernel modules: ath10k_pci + [...] + +The line starting with 'Kernel modules:' tells us the hardware is driven by a +module called ´´ath10k_pci´´. If you now search for 'ath10k' in the MAINTAINER +file you will find something like this:: + + QUALCOMM ATHEROS ATH10K WIRELESS DRIVER + M: Some Human + L: ath10k@lists.infradead.org + W: http://wireless.kernel.org/en/users/Drivers/ath10k + T: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git + S: Supported + F: drivers/net/wireless/ath/ath10k/ + +First look out for line starting with 'S:', to make sure the code is +'Supported', 'Maintained', or at least has someone that provides 'Odd Fixes' if +the person has a spare minute. If it states 'Obsolete' then you are using some +outdated code and should switch to the newer approach the kernel offers. If it +says 'Orphan' you are out of luck: nobody takes care of the code anymore, hence +there is nobody to send a report to. You need to fix this yourself or look +somewhere else to find someone that is willing to help. + +Now look for a line starting with 'B:', as that will tell you where to find a +bug tracker to file your issue. The example does not have such a line; that +is the case for most sections, as Linux kernel development is completely driven +by mail and only a few developers use a bug tracker. + +Thus, if there is no 'B:' look for lines staring with 'M:'. Those mention the +name and the email addresses for the maintainers of the particular code. Also +look for one starting with 'L:', which tells you the public mailing list where +the code is developed. Your report later needs to go by mail to those addresses. +Don't omit the mailing list when sending your issue report by mail! Maintainers +are busy people and might leave some work for other developers on the list. + +Additionally, for all issue report send by mail make sure to also CC the Linux +Kernel Mailing List , commonly known as LKML. That +won't increase visibility, as almost no kernel developer reads that list anymore +due to its high traffic. But it will ensure the report can be found with a +search in the LKML archives. + +If your curious what the other letters stand for search the MAINTAINER file +near the top for a section 'Descriptions of section entries and preferred +order'. + +Finding the maintainers with the help of a script +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For people that have the Linux sources at hand there is an even better way to +find the proper place to report, as it contains a script that tries to find all +people to contact. This script will need a path to the source code in question. +For drivers if often can be found with a command like this:: + + $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!' + drivers/net/wireless/ath/ath10k/ath10k_pci + +Pass that part to the script:: + + $ ./scripts/get_maintainer.pl -f drivers/net/wireless/ath/ath10k* + Some Human (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + Another S. Human (odd fixer:NETWORKING DRIVERS) + ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIRELESS)) + netdev@vger.kernel.org (open list:NETWORKING DRIVERS) + linux-kernel@vger.kernel.org (open list) + +Don't sent the initial report to all of them, stick to the maintainer and the +mailing list initially ('Some Human ' and +'ath10k@lists.infradead.org'). But you might want to contact the others later +in case the maintainer is not reacting appropriately, as outlined in a later +section of this document. + +A note for developer and experts: in case you cloned the Linux sources with git +you might want to add ``--git`` when calling ``get_maintainer.pl``. The script +then will look at the git commit history to find which people recently worked +on the code in question. That sometimes gives a better result, but sometimes +sends people in a wrong direction. The latter for example happens with code +that is changed rarely (like old or unmaintained drivers), as such code is +sometimes modified during tree-wide cleanups by developers that do not care +about the particular code at all. Hence, use this option with care. + + .. ############################################################################ .. Temporary marker added while this document is rewritten. Sections above .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old. @@ -392,51 +513,6 @@ How to report Linux kernel bugs =============================== -Identify the problematic subsystem ----------------------------------- - -Identifying which part of the Linux kernel might be causing your issue -increases your chances of getting your bug fixed. Simply posting to the -generic linux-kernel mailing list (LKML) may cause your bug report to be -lost in the noise of a mailing list that gets 1000+ emails a day. - -Instead, try to figure out which kernel subsystem is causing the issue, -and email that subsystem's maintainer and mailing list. If the subsystem -maintainer doesn't answer, then expand your scope to mailing lists like -LKML. - - -Identify who to notify ----------------------- - -Once you know the subsystem that is causing the issue, you should send a -bug report. Some maintainers prefer bugs to be reported via bugzilla -(https://bugzilla.kernel.org), while others prefer that bugs be reported -via the subsystem mailing list. - -To find out where to send an emailed bug report, find your subsystem or -device driver in the MAINTAINERS file. Search in the file for relevant -entries, and send your bug report to the person(s) listed in the "M:" -lines, making sure to Cc the mailing list(s) in the "L:" lines. When the -maintainer replies to you, make sure to 'Reply-all' in order to keep the -public mailing list(s) in the email thread. - -If you know which driver is causing issues, you can pass one of the driver -files to the get_maintainer.pl script:: - - perl scripts/get_maintainer.pl -f - -If it is a security bug, please copy the Security Contact listed in the -MAINTAINERS file. They can help coordinate bugfix and disclosure. See -:ref:`Documentation/admin-guide/security-bugs.rst ` for more information. - -If you can't figure out which subsystem caused the issue, you should file -a bug in kernel.org bugzilla and send email to -linux-kernel@vger.kernel.org, referencing the bugzilla URL. (For more -information on the linux-kernel mailing list see -http://vger.kernel.org/lkml/). - - Tips for reporting bugs ----------------------- -- 2.26.2