linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Randy Dunlap <rdunlap@infradead.org>
To: Thorsten Leemhuis <linux@leemhuis.info>,
	Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [RFC PATCH v1 09/26] docs: reporting-bugs: help users find the proper place for their report
Date: Sat, 3 Oct 2020 21:03:25 -0700	[thread overview]
Message-ID: <24dfc4c3-5c53-be63-4768-a3c8b5a42706@infradead.org> (raw)
In-Reply-To: <d612f512f2e4eb00e1e80674783c1ffb5e463f82.1601541165.git.linux@leemhuis.info>

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> 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 <linux@leemhuis.info>
> ---
> 
> = 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).

Yes, LKML has become an archival list for almost everything. However, bug reports
should still be sent to their more specific list when possible, e.g., USB to
linux-usb, ACPI to linux-acpi, networking to netdev, wireless to linux-wireless,
SCSI to linux-scsi, etc.

I might be OK with one additional bug/issues/regressions mailing list but I
wouldn't care to see that split into more than one list.

> ---
>  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

                                                                             is a 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
> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_,

The MAINTAINERS list is also available via html at
https://www.kernel.org/doc/html/latest/process/maintainers.html

but since a reporter might need to use scripts/get_maintainer.pl, maybe the html
doesn't help so much.

> +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

                     MAINTAINERS

> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +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::

Other times it might be 'lsusb' or 'lsscsi' or this might not be applicable at all
to LED drivers or pinctrl drivers or W1 or I2C or GPIO (?).

> +
> +       [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

                                                                       MAINTAINERS

> +file you will find something like this::
> +
> +       QUALCOMM ATHEROS ATH10K WIRELESS DRIVER
> +       M:      Some Human <shuman@example.com>
> +       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

s/out//

> +'Supported', 'Maintained', or at least has someone that provides 'Odd Fixes' if

I would s/that/who/ but it seems that "that" is also acceptable.

> +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.

or discard that particular hardware.

> +
> +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

                               reports sent by email,

> +Kernel Mailing List <linux-kernel@vger.kernel.org>, 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

      you're                                                   MAINTAINERS

> +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 <shuman@example.com> (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER)
> +       Another S. Human <asomehuman@example.com> (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 <shuman@example.com>' 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.

Personally I would CC all M: people but not R: (reviewers).

> +
> +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 <filename>
> -
> -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 <securitybugs>` 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
>  -----------------------
>  
> 


-- 
~Randy


  reply	other threads:[~2020-10-04  4:03 UTC|newest]

Thread overview: 75+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-10-01  8:39 [RFC PATCH v1 00/26] Make reporting-bugs easier to grasp and yet more detailed Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 01/26] docs: reporting-bugs: temporary markers for licensing and diff reasons Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues Thorsten Leemhuis
2020-10-02  2:32   ` Randy Dunlap
2020-10-03  7:27     ` Thorsten Leemhuis
2020-11-11 15:24       ` Thorsten Leemhuis
2020-11-12  3:33         ` Randy Dunlap
2020-11-12  4:56           ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 03/26] docs: reporting-bugs: step-by-step guide on " Thorsten Leemhuis
2020-10-02  3:02   ` Randy Dunlap
2020-10-03  8:05     ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 04/26] docs: reporting-bugs: step-by-step guide for issues in stable & longterm Thorsten Leemhuis
2020-10-02  3:25   ` Randy Dunlap
2020-10-03  8:24     ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 05/26] docs: reporting-bugs: begin reference section providing details Thorsten Leemhuis
2020-10-02 16:49   ` Randy Dunlap
2020-10-03  8:27     ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 06/26] docs: reporting-bugs: point out we only care about fresh vanilla kernels Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 07/26] docs: reporting-bugs: let users classify their issue Thorsten Leemhuis
2020-10-02 16:59   ` Randy Dunlap
2020-10-03  9:42     ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 08/26] docs: reporting-bugs: make readers check the taint flag Thorsten Leemhuis
2020-10-02 17:08   ` Randy Dunlap
2020-10-03  9:56     ` Thorsten Leemhuis
2020-10-03 17:47       ` Randy Dunlap
2020-10-01  8:39 ` [RFC PATCH v1 09/26] docs: reporting-bugs: help users find the proper place for their report Thorsten Leemhuis
2020-10-04  4:03   ` Randy Dunlap [this message]
2020-10-07 12:05     ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 10/26] docs: reporting-bugs: remind people to look for existing reports Thorsten Leemhuis
2020-10-02 17:17   ` Randy Dunlap
2020-10-03  9:58     ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 11/26] docs: reporting-bugs: remind people to back up their data Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 12/26] docs: reporting-bugs: tell users to disable DKMS et al Thorsten Leemhuis
2020-10-02 17:28   ` Randy Dunlap
2020-10-03  9:59     ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 13/26] docs: reporting-bugs: point out the environment might be causing issue Thorsten Leemhuis
2020-10-02 17:32   ` Randy Dunlap
2020-10-03 10:00     ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 14/26] docs: reporting-bugs: make users write notes, one for each issue Thorsten Leemhuis
2020-10-02 17:35   ` Randy Dunlap
2020-10-03 10:01     ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 15/26] docs: reporting-bugs: make readers test mainline, but leave a loophole Thorsten Leemhuis
2020-10-02 17:51   ` Randy Dunlap
2020-10-03 10:11     ` Thorsten Leemhuis
2020-11-11 15:36       ` Thorsten Leemhuis
2020-11-12  3:42         ` Randy Dunlap
2020-11-12  5:22           ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 16/26] docs: reporting-bugs: let users check taint status again Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 17/26] docs: reporting-bugs: explain options if reproducing on mainline fails Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 18/26] docs: reporting-bugs: let users optimize their notes Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 19/26] docs: reporting-bugs: decode failure messages [need help] Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 20/26] docs: reporting-bugs: instructions for handling regressions Thorsten Leemhuis
2020-10-04  4:03   ` Randy Dunlap
2020-10-04  6:31     ` Thorsten Leemhuis
2020-10-01  8:39 ` [RFC PATCH v1 21/26] docs: reporting-bugs: details on writing and sending the report Thorsten Leemhuis
2020-10-09  2:45   ` Randy Dunlap
2020-10-09  7:38     ` Thorsten Leemhuis
2020-10-01  8:50 ` [RFC PATCH v1 22/26] docs: reporting-bugs: explain what users should do once the report got out Thorsten Leemhuis
2020-10-09 17:37   ` Randy Dunlap
2020-10-11 13:29     ` Thorsten Leemhuis
2020-10-11 15:06       ` Randy Dunlap
2020-10-01  8:50 ` [RFC PATCH v1 23/26] docs: reporting-bugs: details for issues specific to stable and longterm Thorsten Leemhuis
2020-10-09 18:42   ` Randy Dunlap
2020-10-11 13:29     ` Thorsten Leemhuis
2020-10-01  8:50 ` [RFC PATCH v1 24/26] docs: reporting-bugs: explain why users might get neither reply nor fix Thorsten Leemhuis
2020-10-04  4:03   ` Randy Dunlap
2020-10-04  6:35     ` Thorsten Leemhuis
2020-10-01  8:50 ` [RFC PATCH v1 25/26] docs: reporting-bugs: explain things could be easier Thorsten Leemhuis
2020-10-04  4:03   ` Randy Dunlap
2020-10-04  6:36     ` Thorsten Leemhuis
2020-10-01  8:50 ` [RFC PATCH v1 26/26] docs: reporting-bugs: add SPDX tag and license hint, remove markers Thorsten Leemhuis
2020-11-09 11:01 ` [RFC PATCH v1 00/26] Make reporting-bugs easier to grasp and yet more detailed Thorsten Leemhuis
2020-11-09 18:21   ` Jonathan Corbet
2020-11-10 12:01     ` Thorsten Leemhuis
2020-11-10  3:23   ` Randy Dunlap

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=24dfc4c3-5c53-be63-4768-a3c8b5a42706@infradead.org \
    --to=rdunlap@infradead.org \
    --cc=corbet@lwn.net \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux@leemhuis.info \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).