[RFC PATCH v1 09/26] docs: reporting-bugs: help users find the proper place for their report

[Thorsten Leemhuis]

Many thx for you comments. Consider all the obvious spelling and

grammatical mistakes you pointed out fixed, I won't mention all of them

in this reply to keep things easier to follow.

Am 04.10.20 um 06:03 schrieb Randy Dunlap:

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:


= 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-iss...@vger.kernel.org' would be best (and while at it maybe also
linux-regressi...@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.


Definitely, that "always CC LKML" above was meant as "in addition" ;-)


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.


Yeah, but we care more about regression and having no way to tell them
apart from bugs might make things hard.


+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
+`_,

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


Ahh, wasn't aware of that, thx for the pointer. I switched over to that 
one and use a "ref:" link. This and these comments…



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

> [...]

+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 (?).

> [...]

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

> [...]

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


…made me revisit the whole section and rewrite a few bits. This is how 
it looks like now (sorry, please ignore the long quoted lines that got 
wrapped, sending this with thunderbird instead of git-send-email):


```

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 a big project and most of its developers are only familiar 
with a small subset of it. Quite a few programmers for example only care 
for just one driver, for example one for a WiFi chip; its developer 
likely will only have small or no knowledge about the internals of more 
remote "subsystems", like the TCP stack, the PCIe/PCI subsystem, memory 
management or some other part the driver might be using.


Problem is: the Linux kernel lacks a central bug tracker where you can 
simply file your issue to reach the developers that need to know about 
it. That's why you have to find the right place and way to report issues 
yourself. You can do that with the help of a script, but it mainly 
targets kernel developers and experts. For everybody else the 
MAINTAINERS file is the better place.


How to read the MAINTAINERS file
~~
To illustrate how to use the ref:`MAINTAINERS `_ file, lets 

Re: [RFC PATCH v1 09/26] docs: reporting-bugs: help users find the proper place for their report

[Randy Dunlap]

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 
> ---
> 
> = 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-iss...@vger.kernel.org' would be best (and while at it maybe also
> linux-regressi...@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
> +`_,

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:

[RFC PATCH v1 09/26] docs: reporting-bugs: help users find the proper place for their report

[Thorsten Leemhuis]

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-iss...@vger.kernel.org' would be best (and while at it maybe also
linux-regressi...@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:  ath...@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