[RFC PATCH v1 00/26] Make reporting-bugs easier to grasp and yet more detailed

[RFC PATCH v1 00/26] Make reporting-bugs easier to grasp and yet more detailed

[Thorsten Leemhuis]

This series rewrites the "how to report bugs to the Linux kernel maintainers"
document to make it more straight forward and the essence easier to grasp. At
the same time make the text provide a lot more details about the process in form
of a reference section, so users that want or need to know them have them at
hand.

The goal of this rewrite: improve the quality of the bug reports and reduce the
number of reports that get ignored. This was motivated by many reports of poor
quality the main author of the rewrite stumped upon when he was tracking
regressions.

For the curious, this is how the text looks in the end:
https://gitlab.com/knurd42/linux/-/raw/reporting-bugs-rfc/Documentation/admin-guide/reporting-bugs.rst

For comparison, here you can find the old text and the commits to it and its
predecessor:
https://www.kernel.org/doc/html/latest/admin-guide/reporting-bugs.html
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-bugs.rst
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/Documentation/admin-guide/reporting-bugs.rst
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/REPORTING-BUGS

This is an early RFC and likely has some spelling and grammatical mistakes.
Sorry for that, the main author is not a native English speaker and makes too
many of those mistakes even in his mother tongue. He used hunspell and
LanguageTool to find errors, but noticed those tools miss quite a few mistakes.
Hopefully it's not too bad.

The main author of the rewrite is also fully aware the text got quite long in
the end. That happened as he tried to make users avoid many of the problem he
noticed in bug report, which needed quite a bit of space to describe.
Nevertheless, he tried to make sure the text uses a structure where only those
that want to know all the details have to read it. That's mainly realized with
the help of the TL;DR and the short guide at the top of the document. Those
should be good enough for a lot of situations.

There are a few points that will need to be discussed. The comment in the
individual patches will point some of those out; that for example includes
things like "dual licensing under CC-BY 4.0", "are we asking too much from users
when telling them to test mainline?", and "CC LKML or something else on all
reports?". But a few points are best raised here:

 * The old and the new reporting-bugs text take a totally different approach to
bugzilla.kernel.org. The old mentions it as the place to file your issue if
you don't know where to go. The new one mentions it rarely and most of the
time warn users that it's often the wrong place to go. This approach was
chosen as the main author noticed quite a few users (or even a lot?) get no
reply to the bugs they file in bugzilla. That's kind of expected, as quite a
few (many? most?) of the maintainers don't even get notified when reports for
their subsystem get filed there. Anyway: not getting a reply is something
that is just annoying for users and might make them angry. Improving bugzilla
would be an option, but on the kernel and maintainers summit 2017 (sorry it
took so long) it was agreed on to first go this route, as it's easier to
reach and less controversial, as many maintainers likely are unwilling to
deal with bugzilla.

 * The text states "see above" or "see below" in a few places. Should those be
proper links? But then some anchors will need to be placed manually in a few
places, which slightly hurt readability of the plain text. Could RST or
autosectionlabel help here somewhat (without changing the line
"autosectionlabel_maxdepth = 2" in Documentation/conf.py, which likely is
unwanted)?

 * The new text avoids the word "bug" and uses "issues" instead, as users face
issues which might or might not be caused by bugs. Due to this approach it
might make sense to rename the document to "reporting-issues". But for now
everything is left as it is, as changing the name of a well known file has
downsides; but maybe at least the documents headline should get the
s/bugs/issues/ treatment.

 * How to make sure everybody that cares get a chance to review this? As this is
an early RFC, the author chose to sent it only to the docs maintainer,
linux-docs and LKML, to see how well this approach is received in general.
Once it is agreed that this is the route forward, a lot of other people need
to be CCed to review it; the stable maintainers for example should check if
the section on handling issues with stable and longterm kernels is acceptable
for them. In the end it's something a lot of maintainers might want to take
at least a quick look at, as they will be dealing with the reports. But there
is no easy way to contact all of them (apart from CCing all of them), as most
of them likely don't read LKML anymore. Should the author maybe abuse
ksummit-discuss, as this likely will reach all the major stakeholders Side
note: maybe it would be good to have a list for things like this on vger...

The patch series is against docs-next and can also be found on gitlab:
git://git@gitlab.com:knurd42/linux.git reporting-bugs-rfc

Strictly speaking this series is not bisectable, as the old text it left in
place and removed slowly by the patches in the series when they add new text
that covers the same aspect. Thus, both old and new text are incomplete or
inconsistent (and thus would not build, if we'd talked about code). But that is
only relevant for those that read the text before the series is fully applied.
That seemed like an acceptable downside in this case, as this makes it easier to
compare the old and new approach.

Note: The main autor is not a developer, so he will have gotten a few things in
the procedure wrong. Let him know if you spot something where things are off.

Thorsten Leemhuis (26):
  docs: reporting-bugs: temporary markers for licensing and diff reasons
  docs: reporting-bugs: Create a TLDR how to report issues
  docs: reporting-bugs: step-by-step guide on how to report issues
  docs: reporting-bugs: step-by-step guide for issues in stable &
    longterm
  docs: reporting-bugs: begin reference section providing details
  docs: reporting-bugs: point out we only care about fresh vanilla
    kernels
  docs: reporting-bugs: let users classify their issue
  docs: reporting-bugs: make readers check the taint flag
  docs: reporting-bugs: help users find the proper place for their
    report
  docs: reporting-bugs: remind people to look for existing reports
  docs: reporting-bugs: remind people to back up their data
  docs: reporting-bugs: tell users to disable DKMS et al.
  docs: reporting-bugs: point out the environment might be causing issue
  docs: reporting-bugs: make users write notes, one for each issue
  docs: reporting-bugs: make readers test mainline, but leave a loophole
  docs: reporting-bugs: let users check taint status again
  docs: reporting-bugs: explain options if reproducing on mainline fails
  docs: reporting-bugs: let users optimize their notes
  docs: reporting-bugs: decode failure messages [need help]
  docs: reporting-bugs: instructions for handling regressions
  docs: reporting-bugs: details on writing and sending the report
  docs: reporting-bugs: explain what users should do once the report got
    out
  docs: reporting-bugs: details for issues specific to stable and
    longterm
  docs: reporting-bugs: explain why users might get neither reply nor
    fix
  docs: reporting-bugs: explain things could be easier
  docs: reporting-bugs: add SPDX tag and license hint, remove markers

 Documentation/admin-guide/bug-bisect.rst      |    2 +
 Documentation/admin-guide/reporting-bugs.rst  | 1586 +++++++++++++++--
 Documentation/admin-guide/tainted-kernels.rst |    2 +
 scripts/ver_linux                             |   81 -
 4 files changed, 1441 insertions(+), 230 deletions(-)
 delete mode 100755 scripts/ver_linux


base-commit: e0bc9cf0a7d527ff140f851f6f1a815cc5c48fea
-- 
2.26.2

[RFC PATCH v1 01/26] docs: reporting-bugs: temporary markers for licensing and diff reasons

[Thorsten Leemhuis]

Add two temporary markers for the transition to the rewritten document.

Both tell users that the document is incomplete and partly inconsistent
before all patches from the series got applied. It also points out the
new text is dual-licensed under GPLv2+ and CC-BY 4.0. The latter is
better for documentation in general. It's also more liberal, which is a
nice-to-have for a document like this, as other that makes it possible
for websites and books to republish it or build upon it.

The second marker separates old and new text, which makes diffs a lot
more readable. It's also there for licensing reasons, as it makes is
obvious that all old text is gone in the end. Then a proper SPDX license
tag will get added as well.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---

= RFC =

Let me know if you think dual-licensing was a bad idea or if CC-BY-4.0 is a bad
choice here.
---
 Documentation/admin-guide/reporting-bugs.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 42481ea7b41d..4bbb9132782b 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -3,6 +3,19 @@
 Reporting bugs
 ++++++++++++++
 
+.. ############################################################################
+.. Temporary marker added while this document is rewritten. The sections below
+.. up to a second marker of this kind are new and dual-licensed under GPLv2+
+.. and CC-BY 4.0. Both sections are incomplete as of now and thus might be
+.. inconsistent/not make sense before all patches of the rewrite got applied.
+.. ###########################################################################
+
+.. ############################################################################
+.. 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.
+.. Both sections are incomplete as of now and thus sometimes inconsistent.
+.. ###########################################################################
+
 Background
 ==========
 
-- 
2.26.2

[RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Thorsten Leemhuis]

Get straight to the point in a few paragraphs instead of forcing users
to read quite a bit of text, like the old approach did.

All normally needed fits into the first two paragraphs. The third is
dedicated to issues only happening in stable and longterm kernels, as
things otherwise get hard to follow. At the end explicitly spell out
that some issues need to be handled slightly different.

This TLDR naturally leaves lots of details out. But it will be good
enough in some situations, for example for users that recently reported
an issue or are familiar with reporting issues to FLOSS projects.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 43 ++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 4bbb9132782b..7bde6f32ff72 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -10,6 +10,49 @@ Reporting bugs
 .. inconsistent/not make sense before all patches of the rewrite got applied.
 .. ###########################################################################
 
+
+The short guide (aka TL;DR)
+===========================
+
+This is how you report issues with the Linux kernel to its developers:
+
+If you deal with multiple issues at once, process each of them separately. Try
+your best guess which area of the kernel might be responsible for your issue.
+Check the `MAINTAINERS file
+<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
+how developers of that particular area expect to be told about issues; note,
+it's rarely `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as most
+subsystems expect reports by mail sent to their maintainers and their public
+mailing list!
+
+Check the archives of the determined destination thoroughly for existing
+reports; also search the LKML archives and the internet as a whole. If you can't
+find any, install the `latest Linux mainline version <https://kernel.org/>`_.
+Make sure to use a vanilla kernel and avert any add-on kernel modules externally
+developed; also ensure the kernel is running in a healthy environment and does
+not 'taint' itself before the issue occurs. If you can reproduce it, write a
+report to the destination you determined earlier. Afterwards keep the ball
+rolling by proactive testing, a status update now and then, and helping where
+you can.
+
+You can't reproduce an issue with mainline you want to see fixed in older
+version lines? Then make sure the line you care about still gets support.
+Install its latest release as vanilla kernel. If you can reproduce the issue
+there, try to find the commit that fixed it in mainline or any discussion
+preceding it: those will often mention if backporting is planed or impossible;
+if not, ask for it. In case you don't find anything, check if it's a regression
+specific to the version line that need to be bisected and report just like a
+problem in mainline with the stable mailing list CCed. If you reached this point
+without a solution, ask for advice by mailing the subsystem maintainer with the
+subsystem and stable mailing list in CC.
+
+If you deal with a regression, bisect it to find the culprit and CC or forward
+your report to its developers.
+
+Security issues are typically best report privately; also CC the security team
+or forward your report there.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

Re: [RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Get straight to the point in a few paragraphs instead of forcing users
> to read quite a bit of text, like the old approach did.
> 
> All normally needed fits into the first two paragraphs. The third is
> dedicated to issues only happening in stable and longterm kernels, as
> things otherwise get hard to follow. At the end explicitly spell out
> that some issues need to be handled slightly different.
> 
> This TLDR naturally leaves lots of details out. But it will be good
> enough in some situations, for example for users that recently reported
> an issue or are familiar with reporting issues to FLOSS projects.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 43 ++++++++++++++++++++
>  1 file changed, 43 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 4bbb9132782b..7bde6f32ff72 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -10,6 +10,49 @@ Reporting bugs
>  .. inconsistent/not make sense before all patches of the rewrite got applied.
>  .. ###########################################################################
>  
> +
> +The short guide (aka TL;DR)
> +===========================
> +
> +This is how you report issues with the Linux kernel to its developers:
> +
> +If you deal with multiple issues at once, process each of them separately. Try
> +your best guess which area of the kernel might be responsible for your issue.
> +Check the `MAINTAINERS file
> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
> +how developers of that particular area expect to be told about issues; note,

   for how
?

> +it's rarely `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as most
> +subsystems expect reports by mail sent to their maintainers and their public
> +mailing list!
> +
> +Check the archives of the determined destination thoroughly for existing
> +reports; also search the LKML archives and the internet as a whole. If you can't
> +find any, install the `latest Linux mainline version <https://kernel.org/>`_.
> +Make sure to use a vanilla kernel and avert any add-on kernel modules externally
> +developed; also ensure the kernel is running in a healthy environment and does
> +not 'taint' itself before the issue occurs. If you can reproduce it, write a

I don't care for "does not 'taint' itself". How about
                                                                         and is not
   already tainted before the issue occurs.

> +report to the destination you determined earlier. Afterwards keep the ball
> +rolling by proactive testing, a status update now and then, and helping where
> +you can.
> +
> +You can't reproduce an issue with mainline you want to see fixed in older
> +version lines? Then make sure the line you care about still gets support.
> +Install its latest release as vanilla kernel. If you can reproduce the issue

Is "vanilla" well understood?

> +there, try to find the commit that fixed it in mainline or any discussion
> +preceding it: those will often mention if backporting is planed or impossible;
> +if not, ask for it. In case you don't find anything, check if it's a regression
> +specific to the version line that need to be bisected and report just like a

                                that needs

> +problem in mainline with the stable mailing list CCed. If you reached this point
> +without a solution, ask for advice by mailing the subsystem maintainer with the
> +subsystem and stable mailing list in CC.
> +
> +If you deal with a regression, bisect it to find the culprit and CC or forward
> +your report to its developers.
> +
> +Security issues are typically best report privately; also CC the security team

                                      reported

> +or forward your report there.
> +
> +
>  .. ############################################################################
>  .. 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.
> 


-- 
~Randy

Re: [RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Thorsten Leemhuis]

Randy, many thanks for looking through this, you feedback is much
appreciated! 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 02.10.20 um 04:32 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> […]
>> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
>> +how developers of that particular area expect to be told about issues; note,
>    for how
> ?

Not sure myself, but I guess you're right and thus followed your advice :-D

> […]
>> +Make sure to use a vanilla kernel and avert any add-on kernel modules externally
>> +developed; also ensure the kernel is running in a healthy environment and does
>> +not 'taint' itself before the issue occurs. If you can reproduce it, write a
> 
> I don't care for "does not 'taint' itself". How about
>                                                                          and is not
>    already tainted before the issue occurs.

Hmmm, what I wanted to bring across: the kernel is not tainted when it
arrives, it taints itself after it was started. You suggestion removes
that intention, but now that I read my text again I notice it wasn't
really good at it either. Ohh well, I guess I go with your suggestion,
as it seems bringing that point over it asking for too much here.

> […]
>> +You can't reproduce an issue with mainline you want to see fixed in older
>> +version lines? Then make sure the line you care about still gets support.
>> +Install its latest release as vanilla kernel. If you can reproduce the issue
> 
> Is "vanilla" well understood?

I'd say for the TLDR using it without and explanation is fine. But the
main section didn't prominently mention it, that why I added the first
step slightly and added this:

This kernel must not be modified or enhanced in any way and thus be
'vanilla'.

Ciao, Thorsten

Re: [RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Thorsten Leemhuis]

Am 03.10.20 um 09:27 schrieb Thorsten Leemhuis:
> Randy, many thanks for looking through this, you feedback is much
> appreciated! 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 02.10.20 um 04:32 schrieb Randy Dunlap:
>> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
>> […]
>>> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
>>> +how developers of that particular area expect to be told about issues; note,
>>     for how
>> ?
> Not sure myself, but I guess you're right and thus followed your advice :-D

I'm preparing to send v2 and was a bit unhappy with this and another 
section when seeing it again after weeks. In the end I reshuffled and 
rewrote significant parts of it, see below.

Randy, would be great if you could take another look, but no pressure: 
just ignore it, if you lack the time or energy.

```
The short guide (aka TL;DR)
===========================

If you're facing multiple issues with the Linux kernel at once, report 
each separately to its developers. Try your best guess which kernel part 
might be causing the issue. Check the :ref:`MAINTAINERS <maintainers>` 
file for how its developers expect to be told about issues. Note, it's 
rarely `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as in 
almost all cases the report needs to be sent by email!

Check the destination thoroughly for existing reports; also search the 
LKML archives and the web. Join existing discussion if you find matches. 
If you don't find any, install `the latest Linux mainline kernel 
<https://kernel.org/>`_. Make sure it's vanilla, thus is not patched or 
using add-on kernel modules. Also ensure the kernel is running in a 
healthy environment and is not already tainted before the issue occurs.

If you can reproduce your issue with the mainline kernel, send a report 
to the destination you determined earlier. Make sure it includes all 
relevant information, which in case of a regression should mention the 
change that's causing it which can often can be found with a bisection. 
Also ensure the report reaches all people that need to know about it, 
for example the security team, the stable maintainers or the developers 
of the patch that causes a regression. Once the report it out, answer 
any questions that might be raised and help where you can. That includes 
keeping the ball rolling: every time a new rc1 mainline kernel is 
released, check if the issue is still happening there and attach a 
status update to your initial report.

If you can not reproduce the issue with the mainline kernel, consider 
sticking with it; if you'd like to use an older version line and want to 
see it fixed there, first make sure it's still supported. Install its 
latest release as vanilla kernel. If you cannot reproduce the issue 
there, try to find the commit that fixed it in mainline or any 
discussion preceding it: those will often mention if backporting is 
planed or considered impassable. If backporting was not discussed, ask 
if it's in the cards. In case you don't find any commits or a preceding 
discussion, see the Linux-stable mailing list archives for existing 
reports, as it might be a regression specific to the version line. If it 
is, it round about needs to be reported like a problem in mainline 
(including the bisection).

If you reached this point without a solution, ask for advice one the 
subsystem's mailing list.
```

Ciao, Thorsten

Re: [RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Randy Dunlap]

On 11/11/20 7:24 AM, Thorsten Leemhuis wrote:
> Am 03.10.20 um 09:27 schrieb Thorsten Leemhuis:
>> Randy, many thanks for looking through this, you feedback is much
>> appreciated! 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 02.10.20 um 04:32 schrieb Randy Dunlap:
>>> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
>>> […]
>>>> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
>>>> +how developers of that particular area expect to be told about issues; note,
>>>     for how
>>> ?
>> Not sure myself, but I guess you're right and thus followed your advice :-D
> 
> I'm preparing to send v2 and was a bit unhappy with this and another section when seeing it again after weeks. In the end I reshuffled and rewrote significant parts of it, see below.
> 
> Randy, would be great if you could take another look, but no pressure: just ignore it, if you lack the time or energy.
> 
> ```
> The short guide (aka TL;DR)
> ===========================
> 
> If you're facing multiple issues with the Linux kernel at once, report each separately to its developers. Try your best guess which kernel part might be causing the issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its developers expect to be told about issues. Note, it's rarely `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as in almost all cases the report needs to be sent by email!
> 
> Check the destination thoroughly for existing reports; also search the LKML archives and the web. Join existing discussion if you find matches. If you don't find any, install `the latest Linux mainline kernel <https://kernel.org/>`_. Make sure it's vanilla, thus is not patched or using add-on kernel modules. Also ensure the kernel is running in a healthy environment and is not already tainted before the issue occurs.
> 
> If you can reproduce your issue with the mainline kernel, send a report to the destination you determined earlier. Make sure it includes all relevant information, which in case of a regression should mention the change that's causing it which can often can be found with a bisection. Also ensure the report reaches all people that need to know about it, for example the security team, the stable maintainers or the developers of the patch that causes a regression. Once the report it out, answer any questions that might be raised and help where you can. That includes keeping the ball rolling: every time a new rc1 mainline kernel is released, check if the issue is still happening there and attach a status update to your initial report.
> 
> If you can not reproduce the issue with the mainline kernel, consider sticking with it; if you'd like to use an older version line and want to see it fixed there, first make sure it's still supported. Install its latest release as vanilla kernel. If you cannot reproduce the issue there, try to find the commit that fixed it in mainline or any discussion preceding it: those will often mention if backporting is planed or considered impassable. If backporting was not discussed, ask if it's in the cards. In case you don't find

                                       impossible.  ??

 any commits or a preceding discussion, see the Linux-stable mailing list archives for existing reports, as it might be a regression specific to the version line. If it is, it round about needs to be reported like a problem in mainline (including the bisection).

                                 maybe:  it still needs to be reported like

> 
> If you reached this point without a solution, ask for advice one the subsystem's mailing list.
> ```

Otherwise it looks good to me.

thanks.
-- 
~Randy

Re: [RFC PATCH v1 02/26] docs: reporting-bugs: Create a TLDR how to report issues

[Thorsten Leemhuis]

Am 12.11.20 um 04:33 schrieb Randy Dunlap:
> On 11/11/20 7:24 AM, Thorsten Leemhuis wrote:
>> Am 03.10.20 um 09:27 schrieb Thorsten Leemhuis:
>>> Am 02.10.20 um 04:32 schrieb Randy Dunlap:
>>>> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote: […]
 > […]

Sorry for the mail with those overly long lines, seems Thunderbird does 
not behave as it used to (or I did something stupid) :-/

>> I'm preparing to send v2 and was a bit unhappy with this and
>> another section when seeing it again after weeks. In the end I
>> reshuffled and rewrote significant parts of it, see below.
>> 
>> […]
>> If you can not reproduce the issue with the mainline kernel,
>> consider sticking with it; if you'd like to use an older version
>> line and want to see it fixed there, first make sure it's still
>> supported. Install its latest release as vanilla kernel. If you
>> cannot reproduce the issue there, try to find the commit that fixed
>> it in mainline or any discussion preceding it: those will often
>> mention if backporting is planed or considered impassable. If
>> backporting was not discussed, ask if it's in the cards. In case
>> you don't find
> impossible.  ??

Hmmm, I didn't won't to use "impossible" as it often is possible, but 
considered to hard/to much work. But I guess my dict sent me the wrong way.

I'll guess I'll switch to "considered too complex"

>> any commits or a preceding discussion, see the Linux-stable mailing
>> list archives for existing reports, as it might be a regression
>> specific to the version line. If it is, it round about needs to be
>> reported like a problem in mainline (including the bisection).
> maybe:  it still needs to be reported like

Went with:

If it is, report it like you would report a problem in mainline 
(including the bisection).

>> If you reached this point without a solution, ask for advice one
>> the subsystem's mailing list. ```
> Otherwise it looks good to me.

Many thanks for looking at it, much appreciated!

Ciao, Thorsten

[RFC PATCH v1 03/26] docs: reporting-bugs: step-by-step guide on how to report issues

[Thorsten Leemhuis]

Add a more detailed section on how to report bugs to the Linux kernel
developers that nevertheless still is shorter, more straight-forward and
thus easier to gasp than the old text. It should provide enough details
for most users, even if it still leaves a lot of things unexplained.
Some of them can be important, that's why later patches will add a
reference section describing each of the steps and the motivation for it
in more detail. The text of the particular step will be repeated there
as introduction.

The order of the steps was chosen in the interest of the users: make
sure they get the basics right before they do more complicated,
time-consuming, and dangerous tasks. Some of it also explain a few
basics that might seem natural to kernel developers, but are things that
people often get wrong.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 103 +++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 7bde6f32ff72..203df36af55f 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -53,6 +53,109 @@ Security issues are typically best report privately; also CC the security team
 or forward your report there.
 
 
+Step-by-step guide how to report issues to the kernel maintainers
+=================================================================
+
+Above TL;DR outlines roughly how to report issues to the Linux kernel
+developers. It might be all that's needed for people already familiar with
+reporting issues to Free/Libre & Open Source Software (FLOSS) projects. For
+everyone else there is this section. It is more detailed and uses a
+step-by-step approach. It still tries to be brief for readability; if it's to
+brief for you, look up the details in the reference section below, where each
+of the steps is explained in more detail.
+
+Note, this section covers a few more aspects than the TL;DR and does things in a
+slightly different order. That's in your interest, to make sure you notice early
+if an issue that looks like a Linux kernel problem is actually caused by
+something else. These steps thus help to ensure the time you invest in this
+process won't feel wasted in the end:
+
+ * Stop reading this document and report the problem to your vendor instead,
+   unless you are running a vanilla mainline kernel already or are willing to
+   install it.
+
+ * See if the issue you are dealing with qualifies as regression, security
+   issue, or a really severe problem: those are 'issues of high priority' that
+   need special handling in some steps that are about to follow.
+
+ * Check if your kernel was 'tainted' when the issue occurred, as the event that
+   made the kernel set this flag might be causing the issue you face.
+
+ * 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 <https://bugzilla.kernel.org/>`_, as issues
+   typically need to be sent by mail to a maintainer and a public mailing list.
+
+ * Search the archives of the bug tracker or mailing list in question
+   thoroughly for reports that might match your issue. Also check if you find
+   something with your favorite internet search engine or in the `Linux Kernel
+   Mailing List (LKML) archives <https://lore.kernel.org/lkml/>`_. If you find
+   anything, join the discussion instead of sending a new report.
+
+ * Create a fresh backup and put system repair and restore tools at hand.
+
+ * Ensure your system does not enhance its kernels by building additional
+   kernel modules on-the-fly locally, which solutions like DKMS might be doing
+   without your knowledge.
+
+ * Make sure it's not the kernels surroundings that are causing the issue you
+   face.
+
+ * Write down coarsely how to reproduce the issue. If you deal with multiple
+   issue at once, create separate notes for each of them and make sure they
+   work independently on a freshly booted system. That's needed, as each issue
+   needs to get reported to the kernel developers separately, unless they are
+   strongly entangled.
+
+After these preparations you'll now enter the main part:
+
+ * Install the latest Linux mainline kernel: that's where all issue get fixed
+   first, because it's the version line the kernel developers mainly care about.
+   Testing and reporting with the latest Linux stable kernel can be acceptable
+   alternative in some situations, but is best avoided.
+
+ * Ensure the kernel you just installed does not 'taint' itself when running.
+
+ * Reproduce the issue with the kernel you just installed. If it doesn't show up
+   there, head over to the instructions for issues only happening with stable
+   and longterm kernels if you want to see it fixed there.
+
+ * Optimize your notes: try to find and write the most straightforward way to
+   reproduce your issue. Make sure the end result has all the important details,
+   and at the same time is easy to read and understand for others that hear
+   about it for the first time. And if you learned something in this process,
+   consider searching again for existing reports about the issue.
+
+ * If the failure includes a stack dump, like an Oops does, consider decoding it
+   to find the offending line of code.
+
+ * If your problem is a regression, try to narrow down when the issue was
+   introduced as much as possible.
+
+ * Start to compile the report by writing a detailed description about the
+   issue. Always mentions a few things: the latest kernel version you installed
+   for reproducing, the Linux Distribution used, and your notes how to
+   reproduce the issue. Ideally, make the kernels build configuration (.config)
+   and the output from ``dmesg`` available somewhere on the net and link to it.
+   Include or upload all other information that might be relevant, like the
+   output/screenshot of an Oops or the output from ``lspci``. Once you
+   wrote this main part insert a normal length paragraph on top of it outlining
+   the issue and the impact quickly. On top of this add one sentence that
+   briefly describes the problem and gets people to read on. Now give the thing
+   a descriptive title or subject that yet again is shorter. Then you're ready
+   to send or file the report like the `MAINTAINERS file
+   <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
+   told you, unless you are dealing with one of those 'issues of high priority':
+   they need special care which is explained in 'Special handling for high
+   priority issues' below.
+
+ * Wait for reactions and keep the thing rolling until you can accept the
+   outcome in one way or the other. Thus react publicly and in a timely manner
+   to any inquiries. Test proposed fixes. Do proactive testing when a new rc1
+   gets released. Sent friendly reminders if things stall. And try to help
+   yourself, if you don't get any help or if it is unsatisfying.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

Re: [RFC PATCH v1 03/26] docs: reporting-bugs: step-by-step guide on how to report issues

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 103 +++++++++++++++++++
>  1 file changed, 103 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 7bde6f32ff72..203df36af55f 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -53,6 +53,109 @@ Security issues are typically best report privately; also CC the security team
>  or forward your report there.
>  
>  
> +Step-by-step guide how to report issues to the kernel maintainers
> +=================================================================
> +
> +Above TL;DR outlines roughly how to report issues to the Linux kernel

   The above

> +developers. It might be all that's needed for people already familiar with
> +reporting issues to Free/Libre & Open Source Software (FLOSS) projects. For
> +everyone else there is this section. It is more detailed and uses a
> +step-by-step approach. It still tries to be brief for readability; if it's to

                                                                              too

> +brief for you, look up the details in the reference section below, where each
> +of the steps is explained in more detail.
> +
> +Note, this section covers a few more aspects than the TL;DR and does things in a

   Note:

> +slightly different order. That's in your interest, to make sure you notice early
> +if an issue that looks like a Linux kernel problem is actually caused by
> +something else. These steps thus help to ensure the time you invest in this
> +process won't feel wasted in the end:
> +
> + * Stop reading this document and report the problem to your vendor instead,
> +   unless you are running a vanilla mainline kernel already or are willing to
> +   install it.
> +
> + * See if the issue you are dealing with qualifies as regression, security
> +   issue, or a really severe problem: those are 'issues of high priority' that
> +   need special handling in some steps that are about to follow.
> +
> + * Check if your kernel was 'tainted' when the issue occurred, as the event that
> +   made the kernel set this flag might be causing the issue you face.
> +
> + * 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 <https://bugzilla.kernel.org/>`_, as issues
> +   typically need to be sent by mail to a maintainer and a public mailing list.
> +
> + * Search the archives of the bug tracker or mailing list in question
> +   thoroughly for reports that might match your issue. Also check if you find
> +   something with your favorite internet search engine or in the `Linux Kernel
> +   Mailing List (LKML) archives <https://lore.kernel.org/lkml/>`_. If you find
> +   anything, join the discussion instead of sending a new report.
> +
> + * Create a fresh backup and put system repair and restore tools at hand.
> +
> + * Ensure your system does not enhance its kernels by building additional
> +   kernel modules on-the-fly locally, which solutions like DKMS might be doing
> +   without your knowledge.
> +
> + * Make sure it's not the kernels surroundings that are causing the issue you

                             kernel's

> +   face.
> +
> + * Write down coarsely how to reproduce the issue. If you deal with multiple
> +   issue at once, create separate notes for each of them and make sure they

      issues

> +   work independently on a freshly booted system. That's needed, as each issue
> +   needs to get reported to the kernel developers separately, unless they are
> +   strongly entangled.
> +
> +After these preparations you'll now enter the main part:
> +
> + * Install the latest Linux mainline kernel: that's where all issue get fixed
> +   first, because it's the version line the kernel developers mainly care about.
> +   Testing and reporting with the latest Linux stable kernel can be acceptable

                                                                can be an acceptable

> +   alternative in some situations, but is best avoided.
> +
> + * Ensure the kernel you just installed does not 'taint' itself when running.
> +
> + * Reproduce the issue with the kernel you just installed. If it doesn't show up
> +   there, head over to the instructions for issues only happening with stable
> +   and longterm kernels if you want to see it fixed there.

Can you link (reference) to that section?

> +
> + * Optimize your notes: try to find and write the most straightforward way to
> +   reproduce your issue. Make sure the end result has all the important details,
> +   and at the same time is easy to read and understand for others that hear
> +   about it for the first time. And if you learned something in this process,
> +   consider searching again for existing reports about the issue.
> +
> + * If the failure includes a stack dump, like an Oops does, consider decoding it
> +   to find the offending line of code.

Refer to scripts/decodecode ?
or is that done elsewhere?

> +
> + * If your problem is a regression, try to narrow down when the issue was
> +   introduced as much as possible.
> +
> + * Start to compile the report by writing a detailed description about the
> +   issue. Always mentions a few things: the latest kernel version you installed
> +   for reproducing, the Linux Distribution used, and your notes how to

I would say:                                                 notes on how to
Maybe it's just me.

> +   reproduce the issue. Ideally, make the kernels build configuration (.config)

                                             kernel's

> +   and the output from ``dmesg`` available somewhere on the net and link to it.
> +   Include or upload all other information that might be relevant, like the
> +   output/screenshot of an Oops or the output from ``lspci``. Once you
> +   wrote this main part insert a normal length paragraph on top of it outlining

                      part, insert

> +   the issue and the impact quickly. On top of this add one sentence that
> +   briefly describes the problem and gets people to read on. Now give the thing
> +   a descriptive title or subject that yet again is shorter. Then you're ready
> +   to send or file the report like the `MAINTAINERS file
> +   <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
> +   told you, unless you are dealing with one of those 'issues of high priority':

      tells you,

OK, I like present tense as much as possible.

> +   they need special care which is explained in 'Special handling for high
> +   priority issues' below.

Can we provide a link to that section here?

> +
> + * Wait for reactions and keep the thing rolling until you can accept the
> +   outcome in one way or the other. Thus react publicly and in a timely manner
> +   to any inquiries. Test proposed fixes. Do proactive testing when a new rc1

                                                                  when a new -rc
(release candidate) is released. Send

> +   gets released. Sent friendly reminders if things stall. And try to help
> +   yourself, if you don't get any help or if it is unsatisfying.
> +
> +
>  .. ############################################################################
>  .. 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.
> 


-- 
~Randy

Re: [RFC PATCH v1 03/26] docs: reporting-bugs: step-by-step guide on how to report issues

[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 02.10.20 um 05:02 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> […]
>> +brief for you, look up the details in the reference section below, where each
>> +of the steps is explained in more detail.
>> +
>> +Note, this section covers a few more aspects than the TL;DR and does things in a
>    Note:

Ohh, really? LanguageTool suggested to use the comma once when I forgot
a colon, so I assumed it was okay. Uhhps.


>> + * Reproduce the issue with the kernel you just installed. If it doesn't show up
>> +   there, head over to the instructions for issues only happening with stable
>> +   and longterm kernels if you want to see it fixed there.
> Can you link (reference) to that section?

I raised that problem in the cover letter, as this is not the only place
where it would make sense. Hoping for input from Jonathan here how to do
that without adding lots of anchors...

>> + * Optimize your notes: try to find and write the most straightforward way to
>> +   reproduce your issue. Make sure the end result has all the important details,
>> +   and at the same time is easy to read and understand for others that hear
>> +   about it for the first time. And if you learned something in this process,
>> +   consider searching again for existing reports about the issue.
>> +
>> + * If the failure includes a stack dump, like an Oops does, consider decoding it
>> +   to find the offending line of code.
> Refer to scripts/decodecode ?
> or is that done elsewhere?

Elsewhere and this step and that document likely needs to be heavily
updated anyway, as pointed out in a later patch :-/

>> +
>> + * If your problem is a regression, try to narrow down when the issue was
>> +   introduced as much as possible.
>> +
>> + * Start to compile the report by writing a detailed description about the
>> +   issue. Always mentions a few things: the latest kernel version you installed
>> +   for reproducing, the Linux Distribution used, and your notes how to
> 
> I would say:                                                 notes on how to
> Maybe it's just me.

Googled a bit and to me as a non-native English speaker looks like
you're correct.

>> +   reproduce the issue. Ideally, make the kernels build configuration (.config)
>                                              kernel's

Uggh, sorry, this mistake will show up a few more times, looks like I
applied German grammar rules to English. :-/

>> +   the issue and the impact quickly. On top of this add one sentence that
>> +   briefly describes the problem and gets people to read on. Now give the thing
>> +   a descriptive title or subject that yet again is shorter. Then you're ready
>> +   to send or file the report like the `MAINTAINERS file
>> +   <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
>> +   told you, unless you are dealing with one of those 'issues of high priority':
>       tells you,
> OK, I like present tense as much as possible.

Hmmm. Normally I'd agree, but I used past tense here because it refers
to something the reader did in an earlier step.

>> + * Wait for reactions and keep the thing rolling until you can accept the
>> +   outcome in one way or the other. Thus react publicly and in a timely manner
>> +   to any inquiries. Test proposed fixes. Do proactive testing when a new rc1
>                                                                   when a new -rc
> (release candidate) is released. Send

I only meant "rc1" here, not every rc. More about this in a later patch.

Regarding explaining "rc" as "release candidate": my stupid brain has a
really hard time following that suggestion, as it still remembers some
words someone named Linus Torvalds wrote many many years ago:
```
I'll just use "-rc", and we can all agree that it stands for "Ridiculous
Count" rather than "Release Candidate".
```
https://lore.kernel.org/lkml/Pine.LNX.4.58.0410221821030.2101@ppc970.osdl.org/


I'll go and try to find some pills to force my brain into compliance.
;-) Once they start to work it hopefully can agree to this:

Do proactive testing: retest with at least every first release candidate
(RC) of a new mainline version and report your results.

Ciao, Thorsten

[RFC PATCH v1 04/26] docs: reporting-bugs: step-by-step guide for issues in stable & longterm

[Thorsten Leemhuis]

Handle stable and longterm kernels in a subsection, as dealing with them
directly in the main part of the step-by-step guide turned out to make
it messy and hard to follow: it looked a bit like code with a large
amount of if-then-else section to handle special cases, which made the
default code-flow hard to understand.

Yet again each step will later be repeated in a reference section and
described in more detail.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 49 ++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 203df36af55f..e0a6f4328e87 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -156,6 +156,55 @@ After these preparations you'll now enter the main part:
    yourself, if you don't get any help or if it is unsatisfying.
 
 
+Reporting issues only occurring in older kernel version lines
+-------------------------------------------------------------
+
+This section is for you, if you tried the latest mainline kernel as outlined
+above, but failed to reproduce your issue there; at the same time you want to
+see the issue fixed in older version lines or a vendor kernel that's regularly
+rebased on new stable or longterm releases. If that case follow these steps:
+
+ * Prepare yourself for the possibility that going through the next few steps
+   might not get the issue solved in older releases: the fix might be too big or
+   risky to get backported there.
+
+ * Check if the kernel developers still maintain the Linux kernel version line
+   you care about: go to `the front-page of kernel.org <https://kernel.org>`_
+   and make sure it mentions the latest release of the particular version line
+   without an '[EOL]' tag.
+
+ * Check the `archives of the Linux stable mailing list
+   <https://lore.kernel.org/stable/>`_  for existing reports.
+
+ * Install the latest release from the particular version line as a vanilla
+   kernel. Ensure this kernel is not tainted and still shows the problem, as the
+   issue might have already been fixed there.
+
+ * Search the Linux kernel version control system for the change that fixed
+   the issue in mainline, as its commit message might tell you if the fix is
+   scheduled for backporting already. If you don't find anything that way,
+   search the appropriate mailing lists for posts that discuss such an issue or
+   peer-review possible fixes. That might lead you to the commit with the fix
+   or tell you if it's unsuitable for backporting. If backporting was not
+   considered at all, join the newest discussion, asking if its in the cards.
+
+ * Check if you're dealing with a regression that was never present in
+   mainline by installing the first release of the version line you care about.
+   If the issue doesn't show up with it, you basically need to report the issue
+   with this version like you would report a problem with mainline (see above).
+   This ideally includes a bisection followed by a search for existing reports
+   on the net; with the help of the subject and the two relevant commit-ids. If
+   that doesn't turn up anything, write the report; CC or forward the report to
+   the stable maintainers, the stable mailing list, and those that authored the
+   change. Include the shortened commit-id if you found the change that causes
+   it.
+
+ * One of the former steps should lead to a solution. If that doesn't work out,
+   ask the maintainers for the subsystem that seems to be causing the issue for
+   advice; CC the mailing list for the particular subsystem as well as the
+   stable mailing list.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

Re: [RFC PATCH v1 04/26] docs: reporting-bugs: step-by-step guide for issues in stable & longterm

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Handle stable and longterm kernels in a subsection, as dealing with them
> directly in the main part of the step-by-step guide turned out to make
> it messy and hard to follow: it looked a bit like code with a large
> amount of if-then-else section to handle special cases, which made the
> default code-flow hard to understand.
> 
> Yet again each step will later be repeated in a reference section and
> described in more detail.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 49 ++++++++++++++++++++
>  1 file changed, 49 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 203df36af55f..e0a6f4328e87 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -156,6 +156,55 @@ After these preparations you'll now enter the main part:
>     yourself, if you don't get any help or if it is unsatisfying.
>  
>  
> +Reporting issues only occurring in older kernel version lines
> +-------------------------------------------------------------
> +
> +This section is for you, if you tried the latest mainline kernel as outlined
> +above, but failed to reproduce your issue there; at the same time you want to
> +see the issue fixed in older version lines or a vendor kernel that's regularly
> +rebased on new stable or longterm releases. If that case follow these steps:
> +
> + * Prepare yourself for the possibility that going through the next few steps
> +   might not get the issue solved in older releases: the fix might be too big or
> +   risky to get backported there.
> +
> + * Check if the kernel developers still maintain the Linux kernel version line
> +   you care about: go to `the front-page of kernel.org <https://kernel.org>`_
> +   and make sure it mentions the latest release of the particular version line
> +   without an '[EOL]' tag.

Explain somewhere that EOL = End Of Life (in parens).

> +
> + * Check the `archives of the Linux stable mailing list
> +   <https://lore.kernel.org/stable/>`_  for existing reports.
> +
> + * Install the latest release from the particular version line as a vanilla
> +   kernel. Ensure this kernel is not tainted and still shows the problem, as the
> +   issue might have already been fixed there.
> +
> + * Search the Linux kernel version control system for the change that fixed
> +   the issue in mainline, as its commit message might tell you if the fix is
> +   scheduled for backporting already. If you don't find anything that way,
> +   search the appropriate mailing lists for posts that discuss such an issue or
> +   peer-review possible fixes. That might lead you to the commit with the fix
> +   or tell you if it's unsuitable for backporting. If backporting was not
> +   considered at all, join the newest discussion, asking if its in the cards.

                                                               it's

> +
> + * Check if you're dealing with a regression that was never present in
> +   mainline by installing the first release of the version line you care about.
> +   If the issue doesn't show up with it, you basically need to report the issue
> +   with this version like you would report a problem with mainline (see above).
> +   This ideally includes a bisection followed by a search for existing reports
> +   on the net; with the help of the subject and the two relevant commit-ids. If
> +   that doesn't turn up anything, write the report; CC or forward the report to
> +   the stable maintainers, the stable mailing list, and those that authored the

                                                           those who (?)

> +   change. Include the shortened commit-id if you found the change that causes
> +   it.
> +
> + * One of the former steps should lead to a solution. If that doesn't work out,
> +   ask the maintainers for the subsystem that seems to be causing the issue for
> +   advice; CC the mailing list for the particular subsystem as well as the
> +   stable mailing list.
> +
> +
>  .. ############################################################################
>  .. 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.
> 


-- 
~Randy

Re: [RFC PATCH v1 04/26] docs: reporting-bugs: step-by-step guide for issues in stable & longterm

[Thorsten Leemhuis]

Many thx for you comments. Consider all the obvious spelling and
grammatical mistakes you pointed out fixed, I won't mention them in this
reply to keep things easier to follow.

Am 02.10.20 um 05:25 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:

>> + * Check if the kernel developers still maintain the Linux kernel version line
>> +   you care about: go to `the front-page of kernel.org <https://kernel.org>`_
>> +   and make sure it mentions the latest release of the particular version line
>> +   without an '[EOL]' tag.
> Explain somewhere that EOL = End Of Life (in parens).

The section that describes this step in more detail explains the
acronym. To keep this section short I'd like to omit the explanation
here, as it's a pretty well known term anyway. Hope that's okay for you.

Ciao, Thorsten

[RFC PATCH v1 05/26] docs: reporting-bugs: begin reference section providing details

[Thorsten Leemhuis]

Provide an introduction to the reference section that will provide more
details how to report an issue. Mention a few general things here. Those
are not strictly needed, but likely wise to write down somewhere.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---

= RFC =

Should we keep the links to
https://www.chiark.greenend.org.uk/~sgtatham/bugs.html and
http://www.catb.org/esr/faqs/smart-questions.html? Are they worth it? Or is
there anything similar or better that's a bit fresher and ideally still
maintained?
---
 Documentation/admin-guide/reporting-bugs.rst | 46 +++++++++++++++++---
 1 file changed, 40 insertions(+), 6 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index e0a6f4328e87..be1bce8d43aa 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -205,6 +205,46 @@ rebased on new stable or longterm releases. If that case follow these steps:
    stable mailing list.
 
 
+Reference section: Reporting issues to the kernel maintainers
+=============================================================
+
+The detailed guides above outlines all the mayor steps in brief fashion, which
+should be enough for most people. But sometimes there are situations where even
+experienced users might wonder how to actually do one of those steps. That's
+what this section is for, as it will provide a lot more details on each of the
+steps. Consider this a reference documentation: it's possible to read it from
+top to bottom, but more meant to skim over and a place to look up details in
+case you need them.
+
+A few words of general advice before digging into the details:
+
+ * The Linux kernel developers are well aware this process is complicated and
+   demands more than other FLOSS projects. We'd love to make it simpler, but
+   that would require work in various places as well as infrastructure that
+   would need constant maintenance; nobody has stepped up to do that work, so
+   that's just how things are for now.
+
+ * A warranty or support contract with some vendor doesn't entitle you to
+   request fixes from developers in the upstream Linux kernel community: such
+   contracts are completely outside the scope of the Linux kernel, its
+   development community, and this document. That's why you can't demand
+   anything such a contract guarantees in this context, not even if the
+   developer handling the issue works for the vendor in question. If you want to
+   claim your rights, use the vendors support channel instead. When doing so,
+   you might want to mention you'd like to see the issue fixed in the upstream
+   Linux kernel; motivate them by saying it's the only way to ensure the fix in
+   the end will get incorporated in all Linux distributions.
+
+ * If you never reported an issue to a FLOSS project before you should consider
+   reading `How to Report Bugs Effectively
+   <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
+   and `How To Ask Questions The Smart Way
+   <http://www.catb.org/esr/faqs/smart-questions.html>`_.
+
+With that of the table, find below the details on how to properly report issues
+to the Linux kernel developers.
+
+
 .. ############################################################################
 .. 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.
@@ -281,12 +321,6 @@ http://vger.kernel.org/lkml/).
 Tips for reporting bugs
 -----------------------
 
-If you haven't reported a bug before, please read:
-
-	https://www.chiark.greenend.org.uk/~sgtatham/bugs.html
-
-	http://www.catb.org/esr/faqs/smart-questions.html
-
 It's REALLY important to report bugs that seem unrelated as separate email
 threads or separate bugzilla entries.  If you report several unrelated
 bugs at once, it's difficult for maintainers to tease apart the relevant
-- 
2.26.2

Re: [RFC PATCH v1 05/26] docs: reporting-bugs: begin reference section providing details

[Randy Dunlap]

Hi--

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Provide an introduction to the reference section that will provide more
> details how to report an issue. Mention a few general things here. Those
> are not strictly needed, but likely wise to write down somewhere.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> 
> = RFC =
> 
> Should we keep the links to
> https://www.chiark.greenend.org.uk/~sgtatham/bugs.html and
> http://www.catb.org/esr/faqs/smart-questions.html? Are they worth it? Or is
> there anything similar or better that's a bit fresher and ideally still
> maintained?

Dunno. They are interesting but outdated.

> ---
>  Documentation/admin-guide/reporting-bugs.rst | 46 +++++++++++++++++---
>  1 file changed, 40 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index e0a6f4328e87..be1bce8d43aa 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -205,6 +205,46 @@ rebased on new stable or longterm releases. If that case follow these steps:
>     stable mailing list.
>  
>  
> +Reference section: Reporting issues to the kernel maintainers
> +=============================================================
> +
> +The detailed guides above outlines all the mayor steps in brief fashion, which

                             outline          major

> +should be enough for most people. But sometimes there are situations where even
> +experienced users might wonder how to actually do one of those steps. That's
> +what this section is for, as it will provide a lot more details on each of the
> +steps. Consider this a reference documentation: it's possible to read it from

                        as

> +top to bottom, but more meant to skim over and a place to look up details in
> +case you need them.
> +
> +A few words of general advice before digging into the details:
> +
> + * The Linux kernel developers are well aware this process is complicated and
> +   demands more than other FLOSS projects. We'd love to make it simpler, but
> +   that would require work in various places as well as infrastructure that
> +   would need constant maintenance; nobody has stepped up to do that work, so
> +   that's just how things are for now.
> +
> + * A warranty or support contract with some vendor doesn't entitle you to
> +   request fixes from developers in the upstream Linux kernel community: such
> +   contracts are completely outside the scope of the Linux kernel, its
> +   development community, and this document. That's why you can't demand
> +   anything such a contract guarantees in this context, not even if the
> +   developer handling the issue works for the vendor in question. If you want to
> +   claim your rights, use the vendors support channel instead. When doing so,

                                 vendor's

> +   you might want to mention you'd like to see the issue fixed in the upstream
> +   Linux kernel; motivate them by saying it's the only way to ensure the fix in
> +   the end will get incorporated in all Linux distributions.
> +
> + * If you never reported an issue to a FLOSS project before you should consider
> +   reading `How to Report Bugs Effectively
> +   <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
> +   and `How To Ask Questions The Smart Way
> +   <http://www.catb.org/esr/faqs/smart-questions.html>`_.
> +
> +With that of the table, find below the details on how to properly report issues

             off

> +to the Linux kernel developers.
> +
> +
>  .. ############################################################################
>  .. 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.
> @@ -281,12 +321,6 @@ http://vger.kernel.org/lkml/).
>  Tips for reporting bugs
>  -----------------------
>  
> -If you haven't reported a bug before, please read:
> -
> -	https://www.chiark.greenend.org.uk/~sgtatham/bugs.html
> -
> -	http://www.catb.org/esr/faqs/smart-questions.html
> -
>  It's REALLY important to report bugs that seem unrelated as separate email
>  threads or separate bugzilla entries.  If you report several unrelated
>  bugs at once, it's difficult for maintainers to tease apart the relevant
> 


-- 
~Randy

Re: [RFC PATCH v1 05/26] docs: reporting-bugs: begin reference section providing details

[Thorsten Leemhuis]

Am 02.10.20 um 18:49 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:

Many thx for you comments, all suggestions implemented.

Ciao, Thorsten

[RFC PATCH v1 06/26] docs: reporting-bugs: point out we only care about fresh vanilla kernels

[Thorsten Leemhuis]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=yes, Size: 4409 bytes --]

More explicitly than the old text point out the Linux kernel developers
don't care about vendor kernels. That is obvious to Linux kernel
developers, but something a lot of users fail to gasp, as quite a few
(maybe a lot?) reports on bugzilla.kernel.org show; most of them get
silently ignored, which is frustrating for people that invested time in
preparing and writing the report. Try to minimize that and explain it
properly, as some users will think "why do kernel devs makes things so
complicated for me and force me to install a fresh vanilla kernel".

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---

= RFC =

Should we accept reports for issues with kernel images that are pretty close to
vanilla? But when are they close enough and how to put that line in words? Maybe
something like this (any major distributions missing?):

```Note: Some Linux kernel developers accept reports from vendor kernels that
are known to be close to upstream. That for example is often the case for the
kernels that Debian GNU/Linux Sid or Fedora Rawhide ship, which are close to
mainline. Additionally, Arch Linux, other Fedora releases, and openSUSE
Tumbleweed often use recent stable kernels that are pretty close to upstream,
too. So a report with one of these might be acceptable. But it depends heavily
on the issue in question and some developers nevertheless will ignore report
from these kernels, that's why installing the latest mainline vanilla kernel is
the safe bet.```
---
 Documentation/admin-guide/reporting-bugs.rst | 33 ++++++++++++++++----
 1 file changed, 27 insertions(+), 6 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index be1bce8d43aa..434e1a890dfe 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -245,6 +245,33 @@ With that of the table, find below the details on how to properly report issues
 to the Linux kernel developers.
 
 
+Make sure you're using the upstream Linux kernel
+------------------------------------------------
+
+   *Stop reading this document and report the problem to your vendor instead,
+   unless you are running a vanilla mainline kernel already or are willing to
+   install it.*
+
+Like most programmers, Linux kernel developers don't like to spend time dealing
+with reports for issues that don't even happen with the source code they
+maintain: it's just a waste everybody's time, yours included. That's why you
+later will have to test your issue with the latest 'vanilla kernel': a kernel
+that was build using the Linux sources taken straight from
+`kernel.org <https://kernel.org/>`_ and not modified or enhanced in any way.
+
+Almost all kernels used in devices (Computers, Laptops, Smartphones, Routers,
+…) and most kernels shipped by Linux distributors are ancient from the point of
+kernel development and heavily modified. They thus do not qualify for reporting
+an issue to the Linux kernel developers: the issue you face with such a kernel
+might be fixed already or caused by the changes or additions, even if they look
+small or totally unrelated. That's why issues with such kernels need to be
+reported to the vendor that distributed it. Its developers should look into the
+report and, in case it turns out to be an upstream issue, fix it directly
+upstream or report it there. If the company or project is uncooperative or if
+you want to circumvent it consider installing the mainline kernel yourself; just
+make sure it's the latest one (see below).
+
+
 .. ############################################################################
 .. 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.
@@ -262,12 +289,6 @@ Please see https://www.kernel.org/ for a list of supported kernels.  Any
 kernel marked with [EOL] is "end of life" and will not have any fixes
 backported to it.
 
-If you've found a bug on a kernel version that isn't listed on kernel.org,
-contact your Linux distribution or embedded vendor for support.
-Alternatively, you can attempt to run one of the supported stable or -rc
-kernels, and see if you can reproduce the bug on that.  It's preferable
-to reproduce the bug on the latest -rc kernel.
-
 
 How to report Linux kernel bugs
 ===============================
-- 
2.26.2

[RFC PATCH v1 07/26] docs: reporting-bugs: let users classify their issue

[Thorsten Leemhuis]

Explicitly outline that some issues are more important than others and
thus need to be handled differently in some steps that are about to
follow. This makes things explicit and easy to find if you need to look
up what issues actually qualify as "regression" or a "severe problem".

The alternative would have been: explain each of the three types in the
place where it requires special handling for the first time. But that
makes it quite easy to miss and harder to find when you need to look it
up.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 39 ++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 434e1a890dfe..430a0c3ee0ad 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -272,6 +272,45 @@ you want to circumvent it consider installing the mainline kernel yourself; just
 make sure it's the latest one (see below).
 
 
+Issue of high priority?
+-----------------------
+
+    *See if the issue you are dealing with qualifies as regression, security
+    issue, or a really severe problem: those are 'issues of high priority' that
+    need special handling in some steps that are about to follow.*
+
+Linus Torvalds and the leading Linux kernel developers want to see some issues
+fixed as soon as possible, hence these 'issues of high priority' get handled
+slightly different in the reporting process. Three type of cases qualify:
+regressions, security issues, and really severe problems.
+
+You deal with a 'regression' if something that worked with an older version of
+the Linux kernel does not work with a newer one or somehow works worse with it.
+It thus is a regression when a Wi-Fi driver that did a fine job with Linux 5.7
+somehow misbehaves with 5.8 or doesn't work at all. It's also a regression if
+an application shows erratic behavior with a newer kernel, which might happen
+due to incompatible changes in the interface between the kernel and the
+userland (like procfs and sysfs). Significantly reduced performance or
+increased power consumption also qualify as regression. But keep in mind: the
+new kernel needs to be build with a configuration that is similar to the one
+from the old kernel (see below how to archive that). That's because
+process is sometimes only possible by doing incompatible changes; but to avoid
+regression such changes have to be enabled explicitly during build time
+configuration.
+
+What qualifies as security issue is left to your judgment. Consider reading
+:ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` before
+proceeding.
+
+An issue is a 'really severe problem' when something totally unacceptable bad
+happens. That's for example the case when a Linux kernel corrupts the data it's
+handling or damages hardware it's running on. You're also dealing with a severe
+issue when the kernel suddenly stops working with an error message ('kernel
+panic') or without any farewell note at all. Note: do not confused a 'panic' (a
+fatal error where the kernels stop itself) with a 'Oops' (a recoverable error),
+as the kernel remains running after an 'Oops'.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

Re: [RFC PATCH v1 07/26] docs: reporting-bugs: let users classify their issue

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Explicitly outline that some issues are more important than others and
> thus need to be handled differently in some steps that are about to
> follow. This makes things explicit and easy to find if you need to look
> up what issues actually qualify as "regression" or a "severe problem".
> 
> The alternative would have been: explain each of the three types in the
> place where it requires special handling for the first time. But that
> makes it quite easy to miss and harder to find when you need to look it
> up.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 39 ++++++++++++++++++++
>  1 file changed, 39 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 434e1a890dfe..430a0c3ee0ad 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -272,6 +272,45 @@ you want to circumvent it consider installing the mainline kernel yourself; just
>  make sure it's the latest one (see below).
>  
>  
> +Issue of high priority?
> +-----------------------
> +
> +    *See if the issue you are dealing with qualifies as regression, security
> +    issue, or a really severe problem: those are 'issues of high priority' that
> +    need special handling in some steps that are about to follow.*
> +
> +Linus Torvalds and the leading Linux kernel developers want to see some issues
> +fixed as soon as possible, hence these 'issues of high priority' get handled
> +slightly different in the reporting process. Three type of cases qualify:

            differently
at least that's what I would say. :)

> +regressions, security issues, and really severe problems.
> +
> +You deal with a 'regression' if something that worked with an older version of
> +the Linux kernel does not work with a newer one or somehow works worse with it.
> +It thus is a regression when a Wi-Fi driver that did a fine job with Linux 5.7
> +somehow misbehaves with 5.8 or doesn't work at all. It's also a regression if
> +an application shows erratic behavior with a newer kernel, which might happen
> +due to incompatible changes in the interface between the kernel and the
> +userland (like procfs and sysfs). Significantly reduced performance or
> +increased power consumption also qualify as regression. But keep in mind: the
> +new kernel needs to be build with a configuration that is similar to the one

                          built

> +from the old kernel (see below how to archive that). That's because

                                         achieve

> +process is sometimes only possible by doing incompatible changes; but to avoid

eh?  That's because ... ???

> +regression such changes have to be enabled explicitly during build time
> +configuration.
> +
> +What qualifies as security issue is left to your judgment. Consider reading
> +:ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` before
> +proceeding.
> +
> +An issue is a 'really severe problem' when something totally unacceptable bad

                                                                unacceptably

> +happens. That's for example the case when a Linux kernel corrupts the data it's
> +handling or damages hardware it's running on. You're also dealing with a severe
> +issue when the kernel suddenly stops working with an error message ('kernel
> +panic') or without any farewell note at all. Note: do not confused a 'panic' (a

                                                             confuse

> +fatal error where the kernels stop itself) with a 'Oops' (a recoverable error),
> +as the kernel remains running after an 'Oops'.
> +
> +
>  .. ############################################################################
>  .. 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.
> 


-- 
~Randy
Reported-by: Randy Dunlap <rdunlap@infradead.org>

Re: [RFC PATCH v1 07/26] docs: reporting-bugs: let users classify their issue

[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 02.10.20 um 18:59 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:

>> +Linus Torvalds and the leading Linux kernel developers want to see some issues
>> +fixed as soon as possible, hence these 'issues of high priority' get handled
>> +slightly different in the reporting process. Three type of cases qualify:
> 
>             differently
> at least that's what I would say. :)

/me googles

Yeah, seems you are right, thx.

>> +from the old kernel (see below how to archive that). That's because
>                                         achieve
>> +process is sometimes only possible by doing incompatible changes; but to avoid
> eh?  That's because ... ???

Argh, that was a last minute change :-/ Now reads:

That's because incompatible changes sometimes can not be avoided when
implementing big improvements are implemented; but to avoid

>> +regression such changes have to be enabled explicitly during build time
    regressions
>> +configuration.
>> +

Ciao, Thorsten

[RFC PATCH v1 08/26] docs: reporting-bugs: make readers check the taint flag

[Thorsten Leemhuis]

Tell users early in the process to check the taint flag, as that will
prevent them from investing time into a report that might be worthless.
That way users for example will notice that the issue they face is in
fact caused by an add-on kernel module or and Oops that happened
earlier.

This approach has a downside: users will later have to check the flag
again with the mainline kernel the guide tells them to install. But that
is an acceptable trade-off here, as checking only takes a few seconds
and can easily prevent wasting time in useless testing and debugging.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---

= RFC =

Should "disable DKMS" come before this step? But then the backup step right
before that one would need to be moved as well, as disabling DKMS can mix things
up.
---
 Documentation/admin-guide/reporting-bugs.rst  | 59 +++++++++++++++++++
 Documentation/admin-guide/tainted-kernels.rst |  2 +
 2 files changed, 61 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 430a0c3ee0ad..61b6592ddf74 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -311,6 +311,65 @@ fatal error where the kernels stop itself) with a 'Oops' (a recoverable error),
 as the kernel remains running after an 'Oops'.
 
 
+Check 'taint' flag
+------------------
+
+    *Check if your kernel was 'tainted' when the issue occurred, as the event
+    that made the kernel set this flag might be causing the issue you face.*
+
+The kernel marks itself with a 'taint' flag when something happens that might
+lead to follow-up errors that look totally unrelated. The issue you face might
+be such an error if your kernel is tainted. That's why it's in your interest to
+rule this out early before investing more time into this process. This is the
+only reason why this step is here, as this process later will tell you to
+install the latest mainline kernel and check its taint flag, as that's the
+kernel the report will be mainly about.
+
+On a running system is easy to check if the kernel tainted itself: it's not
+tainted if ``cat /proc/sys/kernel/tainted`` returns '0'. Checking that file is
+impossible in some situations, that's why the kernel also mentions the taint
+status when it reports an internal problem (a 'kernel bug'), a recoverable
+error (a 'kernel Oops') or a non-recoverable error before halting operation (a
+'kernel panic'). Look near the top of the error messages printed when one of
+these occurs and search for a line starting with 'CPU:'. It should end with
+'Not tainted' if the kernel was not tainted beforehand; it was tainted if you
+see 'Tainted:' followed by a few spaces and some letters.
+
+If your kernel is tainted study
+:ref:`Documentation/admin-guide/tainted-kernels.rst <taintedkernels>` to find
+out why and try to eliminate the reason. Often it's because a recoverable error
+(a 'kernel Oops') occurred and the kernel tainted itself, as the kernel knows
+it might misbehave in strange ways after that point. In that case check your
+kernel or system log and look for a section that starts with this::
+
+       Oops: 0000 [#1] SMP
+
+That's the first Oops since boot-up, as the '#1' between the brackets shows.
+Every Oops and any other problem that happen after that point might be a
+follow-up problem to that first Oops, even if they look totally unrelated. Try
+to rule this out by getting rid of that Oops and reproducing the issue
+afterwards. Sometimes simply restarting will be enough, sometimes a change to
+the configuration followed by a reboot can eliminate the Oops. But don't invest
+too much time into this at this point of the process, as the cause for the Oops
+might already be fixed in the newer Linux kernel version you are going to
+install later in this process.
+
+Quite a few kernels are also tainted because an unsuitable kernel modules was
+loaded. This for example is the case if you use Nvidias proprietary graphics
+driver, VirtualBox, or other software that installs its own kernel modules: you
+will have to remove these modules and reboot the system, as they might in fact
+be causing the issue you face.
+
+The kernel also taints itself when it's loading a module that resists in the
+staging tree of the Linux kernel source. That's a special area for code (mostly
+drivers) that does not yet fulfill the normal Linux kernel quality standards.
+When you report an issue with such a module it's obviously okay if the kernel is
+tainted, just make sure the module in question is the only reason for the taint.
+If the issue happens in an unrelated area reboot and temporary block the module
+from being loaded by specifying ``foo.blacklist=1`` as kernel parameter (replace
+'foo' with the name of the module in question).
+
+
 .. ############################################################################
 .. 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.
diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst
index abf804719890..2900f477f42f 100644
--- a/Documentation/admin-guide/tainted-kernels.rst
+++ b/Documentation/admin-guide/tainted-kernels.rst
@@ -1,3 +1,5 @@
+.. _taintedkernels:
+
 Tainted kernels
 ---------------
 
-- 
2.26.2

Re: [RFC PATCH v1 08/26] docs: reporting-bugs: make readers check the taint flag

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Tell users early in the process to check the taint flag, as that will
> prevent them from investing time into a report that might be worthless.
> That way users for example will notice that the issue they face is in
> fact caused by an add-on kernel module or and Oops that happened
> earlier.
> 
> This approach has a downside: users will later have to check the flag
> again with the mainline kernel the guide tells them to install. But that
> is an acceptable trade-off here, as checking only takes a few seconds
> and can easily prevent wasting time in useless testing and debugging.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> 
> = RFC =
> 
> Should "disable DKMS" come before this step? But then the backup step right
> before that one would need to be moved as well, as disabling DKMS can mix things
> up.
> ---
>  Documentation/admin-guide/reporting-bugs.rst  | 59 +++++++++++++++++++
>  Documentation/admin-guide/tainted-kernels.rst |  2 +
>  2 files changed, 61 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 430a0c3ee0ad..61b6592ddf74 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -311,6 +311,65 @@ fatal error where the kernels stop itself) with a 'Oops' (a recoverable error),
>  as the kernel remains running after an 'Oops'.
>  
>  
> +Check 'taint' flag
> +------------------
> +
> +    *Check if your kernel was 'tainted' when the issue occurred, as the event
> +    that made the kernel set this flag might be causing the issue you face.*
> +
> +The kernel marks itself with a 'taint' flag when something happens that might
> +lead to follow-up errors that look totally unrelated. The issue you face might
> +be such an error if your kernel is tainted. That's why it's in your interest to
> +rule this out early before investing more time into this process. This is the
> +only reason why this step is here, as this process later will tell you to
> +install the latest mainline kernel and check its taint flag, as that's the
> +kernel the report will be mainly about.
> +
> +On a running system is easy to check if the kernel tainted itself: it's not
> +tainted if ``cat /proc/sys/kernel/tainted`` returns '0'. Checking that file is
> +impossible in some situations, that's why the kernel also mentions the taint

                      situations;

> +status when it reports an internal problem (a 'kernel bug'), a recoverable
> +error (a 'kernel Oops') or a non-recoverable error before halting operation (a
> +'kernel panic'). Look near the top of the error messages printed when one of
> +these occurs and search for a line starting with 'CPU:'. It should end with
> +'Not tainted' if the kernel was not tainted beforehand; it was tainted if you
> +see 'Tainted:' followed by a few spaces and some letters.
> +
> +If your kernel is tainted study

                     tainted, study

> +:ref:`Documentation/admin-guide/tainted-kernels.rst <taintedkernels>` to find
> +out why and try to eliminate the reason. Often it's because a recoverable error
> +(a 'kernel Oops') occurred and the kernel tainted itself, as the kernel knows
> +it might misbehave in strange ways after that point. In that case check your
> +kernel or system log and look for a section that starts with this::
> +
> +       Oops: 0000 [#1] SMP
> +
> +That's the first Oops since boot-up, as the '#1' between the brackets shows.
> +Every Oops and any other problem that happen after that point might be a
> +follow-up problem to that first Oops, even if they look totally unrelated. Try
> +to rule this out by getting rid of that Oops and reproducing the issue
> +afterwards. Sometimes simply restarting will be enough, sometimes a change to
> +the configuration followed by a reboot can eliminate the Oops. But don't invest
> +too much time into this at this point of the process, as the cause for the Oops
> +might already be fixed in the newer Linux kernel version you are going to
> +install later in this process.
> +
> +Quite a few kernels are also tainted because an unsuitable kernel modules was

                                                                     module

> +loaded. This for example is the case if you use Nvidias proprietary graphics

                                                   Nvidia's

> +driver, VirtualBox, or other software that installs its own kernel modules: you
> +will have to remove these modules and reboot the system, as they might in fact
> +be causing the issue you face.

You will need to reboot the system and try to reproduce the issue without loading
any of these proprietary modules.

> +
> +The kernel also taints itself when it's loading a module that resists in the

                                                                 resides

> +staging tree of the Linux kernel source. That's a special area for code (mostly
> +drivers) that does not yet fulfill the normal Linux kernel quality standards.
> +When you report an issue with such a module it's obviously okay if the kernel is
> +tainted, just make sure the module in question is the only reason for the taint.

   tainted;

> +If the issue happens in an unrelated area reboot and temporary block the module

                                                        temporarily

> +from being loaded by specifying ``foo.blacklist=1`` as kernel parameter (replace
> +'foo' with the name of the module in question).
> +
> +
>  .. ############################################################################
>  .. 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.
> diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst
> index abf804719890..2900f477f42f 100644
> --- a/Documentation/admin-guide/tainted-kernels.rst
> +++ b/Documentation/admin-guide/tainted-kernels.rst
> @@ -1,3 +1,5 @@
> +.. _taintedkernels:
> +
>  Tainted kernels
>  ---------------
>  
> 


-- 
~Randy

Re: [RFC PATCH v1 08/26] docs: reporting-bugs: make readers check the taint flag

[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 02.10.20 um 19:08 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:

>> +driver, VirtualBox, or other software that installs its own kernel modules: you
>> +will have to remove these modules and reboot the system, as they might in fact
>> +be causing the issue you face.
> You will need to reboot the system and try to reproduce the issue without loading
> any of these proprietary modules.

Hmmm. Preventing the Nvidia module from loading without disabling or
uninstalling the other parts of the graphics driver can easily to a
situation where the GUI is not starting. And blacklisting all modules
that VirtualBox needs on the host requires quite a bit of tying at the
boot loader iirc. So how about this:

Quite a few kernels are also tainted because an unsuitable kernel module
was loaded. This for example is the case if you use Nvidia's proprietary
graphics driver, VirtualBox, or other software that installs its own
kernel modules, as they might be causing the issue you face. You thus
have to prevent those modules from loading for the reporting process.
Most of the time the easiest way to do that is: temporarily uninstall
such software including any modules they might have installed.
Afterwards reboot.

Ciao, Thorsten

Re: [RFC PATCH v1 08/26] docs: reporting-bugs: make readers check the taint flag

[Randy Dunlap]

On 10/3/20 2:56 AM, Thorsten Leemhuis wrote:
> 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 02.10.20 um 19:08 schrieb Randy Dunlap:
>> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> 
>>> +driver, VirtualBox, or other software that installs its own kernel modules: you
>>> +will have to remove these modules and reboot the system, as they might in fact
>>> +be causing the issue you face.
>> You will need to reboot the system and try to reproduce the issue without loading
>> any of these proprietary modules.
> 
> Hmmm. Preventing the Nvidia module from loading without disabling or
> uninstalling the other parts of the graphics driver can easily to a
> situation where the GUI is not starting. And blacklisting all modules
> that VirtualBox needs on the host requires quite a bit of tying at the
> boot loader iirc. So how about this:
> 
> Quite a few kernels are also tainted because an unsuitable kernel module
> was loaded. This for example is the case if you use Nvidia's proprietary
> graphics driver, VirtualBox, or other software that installs its own
> kernel modules, as they might be causing the issue you face. You thus
> have to prevent those modules from loading for the reporting process.
> Most of the time the easiest way to do that is: temporarily uninstall
> such software including any modules they might have installed.
> Afterwards reboot.

Sure, OK.

thanks.
-- 
~Randy

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

[Thorsten Leemhuis]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=yes, Size: 10974 bytes --]

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

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

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

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

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 <maintainers>`_ file, lets 
assume the WiFi in your Laptop suddenly misbehaves after updating the 
kernel. In that case it's likely an issue in the WiFi driver. Obviously 
it could also be some code it builds upon, but unless you suspect 
something like that stick to the driver, as its developers will get the 
right people involved if it's really something else.

Sadly, there is no way to check which code is driving a particular 
hardware component that is both universal and easy. In the case of a 
WiFi driver problem there are multiple approaches to find the

You for example might want to look at the output of ``lspci -k``, as it 
lists devices on the PCI/PCIe bus and the kernel module driving it::

        [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
        [...]

But this approach won't work if your WiFi chip is connected over USB or 
some other internal bus. In those cases you might want to check your 
WiFi manager or the output of ``ip link``. Look for the name of the 
problematic network interface, which might be something like 'wlp58s0'. 
This name can be used like this to find the module driving it::

        [user@something ~]$ realpath --relative-to=/sys/module/ 
/sys/class/net/wlp58s0/device/driver/module
        ath10k_pci

In case tricks like these don't bring you any further, try to search the 
internet on how to narrow down the driver or subsystem in question. And 
if you are unsure which it is: just try your best guess, somebody will 
help you if you guess poorly.

Once you know the driver or subsystem you want to search for it in the 
MAINTAINERS file. In the case of 'ath10k_pci' you won't find anything, 
as the name is too specific. Sometimes you will need to search on the 
net then; but before doing so, try to search for a somewhat shorted or 
modified name, as then you might find something like this::

        QUALCOMM ATHEROS ATH10K WIRELESS DRIVER
        Mail:          A. Some Human <shuman@example.com>
        Mailing list:  ath10k@lists.infradead.org
        Status:        Supported
        Web-page: 
https://wireless.wiki.kernel.org/en/users/Drivers/ath10k
        SCM:           git 
git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git
        Files:         drivers/net/wireless/ath/ath10k/

Note: the line description will be abbreviations, if you read the plain 
MAINTAINERS file found in the root of the Linux source tree. 'Mail:' for 
example will be 'M:', 'Mailing list:' will be 'L', and 'Status:' will be 
'S:'. These and other abbreviations are explained near the top of the file.

First look at the line 'Status', to make sure the code is 'Supported', 
'Maintained', or at least has someone who provides 'Odd Fixes' when 
feeling motivated. If it states 'Obsolete' then you are using some 
outdated approach that was replaced by a newer solution you need to 
switch to. With 'Orphan' you are out of luck, as nobody takes care of 
the code anymore, which only leaves these options: stop trying to do 
what you want, live with the issue, fix it yourself, or find a 
programmer somewhere willing to fix it.

After checking the status, look for a line starting with 'bugs:': it 
will tell you where to find a subsystem specific bug tracker to file 
your issue. The example above does not have such a line; that is the 
case for most sections, as Linux kernel development is completely driven 
by mail and only very few subsystems use a bug tracker.

In this in many other cases you thus have to look for lines starting 
with 'Mail:' instead. Those mention the name and the email addresses for 
the maintainers of the particular code. Also look for a line starting 
with 'Mailing list:', which tells you the public mailing list where the 
code is developed. Your report later needs to go by mail to those 
addresses. Additionally, for all issue reports sent by email, make sure 
to add the Linux Kernel Mailing List (LKML) 
<linux-kernel@vger.kernel.org> to CC. Don't omit either of the mailing 
lists when sending your issue report by mail later! Maintainers are busy 
people and might leave some work for other developers on the subsystem 
specific list; and LKML is important to have one place where all issue 
reports can be found.


Finding the maintainers with the help of a script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For people that have the Linux sources at hand there is a second option 
to find the proper place to report: a script that tries to find all 
people to contact. This script is called 'get_maintainer.pl' and located 
in the scripts/ directory and relies on the MAINTAINERS file. It needs 
to be called with a path to the source code in question. For drivers 
compiled as module 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.ko

Pass parts of this 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> (maintainer: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 your report to all of them. Sent it to the maintainers, which 
the script calls "supporter:"; additionally CC the most specific mailing 
list for the code as well as Linux Kernel Mailing List (LKML). In this 
case you thus would need to send the report to 'Some Human 
<shuman@example.com>' with 'ath10k@lists.infradead.org' and 
'linux-kernel@vger.kernel.org' in CC.

Note: in case you cloned the Linux sources with git you might want to 
call ``get_maintainer.pl`` a second time with ``--git``. The script then 
will look at the commit history to find which people recently worked on 
the code in question, as they might be able to help. But use such 
results with care, as it can easily send you in a wrong direction. That 
for example happens quickly with areas that are rarely changed (like old 
or unmaintained drivers): this code is sometimes modified during 
tree-wide cleanups by developers that do not care about the particular 
part of the kernel at all.
```

Ciao, Thorsten

[RFC PATCH v1 10/26] docs: reporting-bugs: remind people to look for existing reports

[Thorsten Leemhuis]

Tells users to search for existing reports, as not reporting them a
second time is in their own interest. Tel them where to look and provide
a few hints how to search properly, as that is easy to get wrong. That
seems to be especially true when it comes to things like graphics cards
or wifi modules: mentioning the model name often is not much help, but
mentioning its main chip often leads to the results you are looking for.
This might be obvious to kernel developers, but for many users it's not.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---

= RFC =

Have I gone to far in describing how to find good search terms? I got the
impression quite a few users to it poorly.
---
 Documentation/admin-guide/reporting-bugs.rst | 58 ++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 3e9923c9650e..4828e8924136 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -491,6 +491,64 @@ sometimes modified during tree-wide cleanups by developers that do not care
 about the particular code at all. Hence, use this option with care.
 
 
+Search for existing reports
+---------------------------
+
+    *Search the archives of the bug tracker or mailing list in question
+    thoroughly for reports that might match your issue. Also check if you find
+    something with your favorite internet search engine or in the Linux Kernel
+    Mailing List (LKML) archives. If you find anything, join the discussion
+    instead of sending a new report.*
+
+Reporting an issue that someone else already brought forward is often a waste of
+time for everyone involved, especially you as the reporter. So it's in your own
+interest to thoroughly check if somebody reported the issue already. Thus do not
+hurry with this step of the reporting process, spending 30 to 60 minutes or even
+more time can save you and others quite a lot of time and trouble.
+
+The best place to search is the bug tracker or the mailing list where your
+report needs to be filed. You'll find quite a few of those lists on
+`lore.kernel.org/ <https://lore.kernel.org/>`_, but some are hosted in different
+places. That for example is the case for the ath10k Wi-Fi driver used as example
+in the previous step. But you'll often find the archives for these lists easily
+on the net. Searching for 'archive ath10k@lists.infradead.org' for example
+will quickly lead you to the `Info page for the ath10k mailing list
+<https://lists.infradead.org/mailman/listinfo/ath10k>`_, which at the top links
+to its `list archives <https://lists.infradead.org/pipermail/ath10k/>`_.
+
+Sadly this and quite a few other lists miss a way to search the archives. In
+those cases use a regular internet search engine and add something like
+'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which limits
+the results to the archives at that URL.
+
+Additionally, search the internet and the `Linux Kernel Mailing List (LKML)
+archives <https://lore.kernel.org/lkml/>`_, as maybe the real culprit might be
+in some other subsystem. Searching in `bugzilla.kernel.org
+<https://bugzilla.kernel.org/>`_ might also be a good idea, but if you find
+anything there keep in mind: it's not the official place to file reports, hence
+the reports you find there might have not even reached the people responsible
+for the subsystem in question.
+
+If you get flooded with results consider telling your search engine to limit the
+results to posts from the past month or year. And wherever you search, make sure
+to use good search terms; vary them a few times, too. While doing so try to look
+at the issue from perspective of someone else: that will help you to come up
+with other words to use as search terms. Also make sure to not use too many
+search terms at once. Remember to search with and without information like the
+name of the kernel driver or the name of the affected hardware component. But
+its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC') often is
+not much helpful, better use the name of the model line (Radeon 5700), the code
+name of the main chip ('Navi' or 'Navi10'), its manufacturer ('AMD'), and things
+like that.
+
+In case you find an existing report consider joining the discussion, as you
+might be able to provide valuable additional information. That can be important
+even when a fix is prepared or in its final stages already, as developers might
+look for people that can provide additional information or test a proposed fix.
+See the section 'Duties after the report went out' for details how to get
+properly involved.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

Re: [RFC PATCH v1 10/26] docs: reporting-bugs: remind people to look for existing reports

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Tells users to search for existing reports, as not reporting them a
> second time is in their own interest. Tel them where to look and provide
> a few hints how to search properly, as that is easy to get wrong. That
> seems to be especially true when it comes to things like graphics cards
> or wifi modules: mentioning the model name often is not much help, but
> mentioning its main chip often leads to the results you are looking for.
> This might be obvious to kernel developers, but for many users it's not.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> 
> = RFC =
> 
> Have I gone to far in describing how to find good search terms? I got the
> impression quite a few users to it poorly.
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 58 ++++++++++++++++++++
>  1 file changed, 58 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 3e9923c9650e..4828e8924136 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -491,6 +491,64 @@ sometimes modified during tree-wide cleanups by developers that do not care
>  about the particular code at all. Hence, use this option with care.
>  
>  
> +Search for existing reports
> +---------------------------
> +
> +    *Search the archives of the bug tracker or mailing list in question
> +    thoroughly for reports that might match your issue. Also check if you find
> +    something with your favorite internet search engine or in the Linux Kernel
> +    Mailing List (LKML) archives. If you find anything, join the discussion
> +    instead of sending a new report.*
> +
> +Reporting an issue that someone else already brought forward is often a waste of
> +time for everyone involved, especially you as the reporter. So it's in your own
> +interest to thoroughly check if somebody reported the issue already. Thus do not
> +hurry with this step of the reporting process, spending 30 to 60 minutes or even

                                         process. Spending

> +more time can save you and others quite a lot of time and trouble.
> +
> +The best place to search is the bug tracker or the mailing list where your
> +report needs to be filed. You'll find quite a few of those lists on
> +`lore.kernel.org/ <https://lore.kernel.org/>`_, but some are hosted in different
> +places. That for example is the case for the ath10k Wi-Fi driver used as example
> +in the previous step. But you'll often find the archives for these lists easily
> +on the net. Searching for 'archive ath10k@lists.infradead.org' for example
> +will quickly lead you to the `Info page for the ath10k mailing list
> +<https://lists.infradead.org/mailman/listinfo/ath10k>`_, which at the top links
> +to its `list archives <https://lists.infradead.org/pipermail/ath10k/>`_.
> +
> +Sadly this and quite a few other lists miss a way to search the archives. In
> +those cases use a regular internet search engine and add something like
> +'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which limits
> +the results to the archives at that URL.
> +
> +Additionally, search the internet and the `Linux Kernel Mailing List (LKML)
> +archives <https://lore.kernel.org/lkml/>`_, as maybe the real culprit might be
> +in some other subsystem. Searching in `bugzilla.kernel.org
> +<https://bugzilla.kernel.org/>`_ might also be a good idea, but if you find
> +anything there keep in mind: it's not the official place to file reports, hence
> +the reports you find there might have not even reached the people responsible
> +for the subsystem in question.
> +
> +If you get flooded with results consider telling your search engine to limit the
> +results to posts from the past month or year. And wherever you search, make sure
> +to use good search terms; vary them a few times, too. While doing so try to look
> +at the issue from perspective of someone else: that will help you to come up

                from the perspective

> +with other words to use as search terms. Also make sure to not use too many

                                                           not to use
?

> +search terms at once. Remember to search with and without information like the
> +name of the kernel driver or the name of the affected hardware component. But
> +its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC') often is
> +not much helpful, better use the name of the model line (Radeon 5700), the code
> +name of the main chip ('Navi' or 'Navi10'), its manufacturer ('AMD'), and things
> +like that.
> +
> +In case you find an existing report consider joining the discussion, as you

                                report,

> +might be able to provide valuable additional information. That can be important
> +even when a fix is prepared or in its final stages already, as developers might
> +look for people that can provide additional information or test a proposed fix.
> +See the section 'Duties after the report went out' for details how to get

                                                      for details on how to get
I must like more prepostions...

> +properly involved.
> +
> +
>  .. ############################################################################
>  .. 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.
> 


-- 
~Randy

Re: [RFC PATCH v1 10/26] docs: reporting-bugs: remind people to look for existing reports

[Thorsten Leemhuis]

Am 02.10.20 um 19:17 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:

Many thx for you comments, all suggestions implemented.



Ciao, Thorsten

[RFC PATCH v1 11/26] docs: reporting-bugs: remind people to back up their data

[Thorsten Leemhuis]

Add a small reminder that users are best of preparing for emergencies.
Doesn't cost us much and might prevent data-loss for a few people, as
disabling DKMS, installing mainline and other tasks this guide suggest
can break the system in you're unlucky.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 4828e8924136..05de4e0259cb 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -549,6 +549,19 @@ See the section 'Duties after the report went out' for details how to get
 properly involved.
 
 
+Prepare for emergencies
+-----------------------
+
+    *Create a fresh backup and put system repair and restore tools at hand.*
+
+Reminder, you are dealing with computers, and they sometimes do unexpected
+things, especially if you fiddle with crucial parts like the kernel of its
+operating system. That's what you are about to do in this process. Thus, make
+sure to create a fresh backup; also ensure you have all tools at hand to repair
+or reinstall the operating system as well as everything you need to restore the
+backup.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

[RFC PATCH v1 12/26] docs: reporting-bugs: tell users to disable DKMS et al.

[Thorsten Leemhuis]

Tell users to disable solutions like DKMS to make sure the mainline
kernel they have to install later remains vanilla. The old text did not
do that, but back when it was written these solutions were not that
widespread.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 21 ++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 05de4e0259cb..d96b21512c03 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -562,6 +562,27 @@ or reinstall the operating system as well as everything you need to restore the
 backup.
 
 
+Make sure your kernel doesn't get enhanced
+------------------------------------------
+
+    *Ensure your system does not enhance its kernels by building additional
+    kernel modules on-the-fly locally, which solutions like DKMS might be doing
+    without your knowledge.*
+
+Your kernel will stop being 'vanilla' as soon as it loads a kernel module not
+build from the sources used to compile the kernel image itself. That why you
+need to ensure your Linux kernel stays vanilla by removing or disabling
+mechanisms like akmods and DKMS: those might build additional kernel modules
+automatically, for example when your boot into a newly installed Linux kernel
+the first time. Reboot after removing them and any modules they installed.
+
+Note, you might not be aware that your system is using one of these solutions:
+they often get set up silently when you install Nvidias proprietary graphics
+driver, VirtualBox, or other Software that requires a some support from a module
+not part of the Linux kernel. Your package manager might thus force you to
+remove those, too.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

Re: [RFC PATCH v1 12/26] docs: reporting-bugs: tell users to disable DKMS et al.

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Tell users to disable solutions like DKMS to make sure the mainline
> kernel they have to install later remains vanilla. The old text did not
> do that, but back when it was written these solutions were not that
> widespread.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 21 ++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 05de4e0259cb..d96b21512c03 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -562,6 +562,27 @@ or reinstall the operating system as well as everything you need to restore the
>  backup.
>  
>  
> +Make sure your kernel doesn't get enhanced
> +------------------------------------------
> +
> +    *Ensure your system does not enhance its kernels by building additional
> +    kernel modules on-the-fly locally, which solutions like DKMS might be doing
> +    without your knowledge.*
> +
> +Your kernel will stop being 'vanilla' as soon as it loads a kernel module not
> +build from the sources used to compile the kernel image itself. That why you

   built                                                           That is why you

> +need to ensure your Linux kernel stays vanilla by removing or disabling
> +mechanisms like akmods and DKMS: those might build additional kernel modules
> +automatically, for example when your boot into a newly installed Linux kernel
> +the first time. Reboot after removing them and any modules they installed.
> +
> +Note, you might not be aware that your system is using one of these solutions:
> +they often get set up silently when you install Nvidias proprietary graphics

                                                   Nvidia's

> +driver, VirtualBox, or other Software that requires a some support from a module
> +not part of the Linux kernel. Your package manager might thus force you to
> +remove those, too.
> +
> +
>  .. ############################################################################
>  .. 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.
> 


-- 
~Randy

Re: [RFC PATCH v1 12/26] docs: reporting-bugs: tell users to disable DKMS et al.

[Thorsten Leemhuis]

Am 02.10.20 um 19:28 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
>> Tell users to disable solutions like DKMS to make sure the mainline

Many thx for you comments, all suggestions implemented.



Ciao, Thorsten

[RFC PATCH v1 13/26] docs: reporting-bugs: point out the environment might be causing issue

[Thorsten Leemhuis]

Help users to avoid a few pitfalls, as they might be the real reason why
the kernel is acting up somehow.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 34 ++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index d96b21512c03..2292b79cf462 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -583,6 +583,40 @@ not part of the Linux kernel. Your package manager might thus force you to
 remove those, too.
 
 
+Ensure a healthy environment
+----------------------------
+
+    *Make sure it's not the kernels surroundings that are causing the issue you
+    face.*
+
+Problems that look a lot like a kernel issue are sometimes caused by build
+or runtime environment. It's hard to rule out that problem completely, but you
+should minimize it:
+
+ * Use proven tools when building your kernel, as bugs in the compiler or the
+   binutils can cause the resulting kernel to misbehave.
+
+ * Ensure your computer components runs within their design specifications;
+   that's especially important for the main processor, the main memory, and the
+   motherboard. Therefore, stop overclocking when facing a potential kernel
+   issue.
+
+ * Try to make sure it's not faulty hardware that is causing your issue. Bad
+   main memory for example can result in a multitude of issues that will
+   manifest itself in problems looking like kernel issues.
+
+ * If you're dealing with a filesystem issue, you might want to check the file
+   system in question with ``fsck`` before trying to reproduce it again.
+
+ * When dealing with a regression, make sure it's not something else that
+   changed in parallel to updating the kernel. The problem for example might be
+   caused by another software that was updated at the same time. It can also
+   happen that a hardware component coincidentally just broke when you rebooted
+   into a new kernel for the first time. Updating the systems BIOS or changing
+   something in the BIOS Setup can also lead to problems that on the first sight
+   look like a regression.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

Re: [RFC PATCH v1 13/26] docs: reporting-bugs: point out the environment might be causing issue

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Help users to avoid a few pitfalls, as they might be the real reason why
> the kernel is acting up somehow.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 34 ++++++++++++++++++++
>  1 file changed, 34 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index d96b21512c03..2292b79cf462 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -583,6 +583,40 @@ not part of the Linux kernel. Your package manager might thus force you to
>  remove those, too.
>  
>  
> +Ensure a healthy environment
> +----------------------------
> +
> +    *Make sure it's not the kernels surroundings that are causing the issue you

                               kernel's

> +    face.*
> +
> +Problems that look a lot like a kernel issue are sometimes caused by build
> +or runtime environment. It's hard to rule out that problem completely, but you
> +should minimize it:
> +
> + * Use proven tools when building your kernel, as bugs in the compiler or the
> +   binutils can cause the resulting kernel to misbehave.
> +
> + * Ensure your computer components runs within their design specifications;

                                      run

> +   that's especially important for the main processor, the main memory, and the
> +   motherboard. Therefore, stop overclocking when facing a potential kernel
> +   issue.
> +
> + * Try to make sure it's not faulty hardware that is causing your issue. Bad
> +   main memory for example can result in a multitude of issues that will
> +   manifest itself in problems looking like kernel issues.
> +
> + * If you're dealing with a filesystem issue, you might want to check the file
> +   system in question with ``fsck`` before trying to reproduce it again.
> +
> + * When dealing with a regression, make sure it's not something else that
> +   changed in parallel to updating the kernel. The problem for example might be
> +   caused by another software that was updated at the same time. It can also

             by other software

> +   happen that a hardware component coincidentally just broke when you rebooted
> +   into a new kernel for the first time. Updating the systems BIOS or changing
> +   something in the BIOS Setup can also lead to problems that on the first sight
> +   look like a regression.
> +
> +
>  .. ############################################################################
>  .. 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.
> 


-- 
~Randy

Re: [RFC PATCH v1 13/26] docs: reporting-bugs: point out the environment might be causing issue

[Thorsten Leemhuis]

Am 02.10.20 um 19:32 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:

Many thx for you comments, all suggestions implemented.



Ciao, Thorsten

[RFC PATCH v1 14/26] docs: reporting-bugs: make users write notes, one for each issue

[Thorsten Leemhuis]

Tell users to write some rough notes how to reproduce the issue. They
will need those notes soon once they have to reproduce the issue with
the latest mainline kernel. At the same time they can serve as basis for
the report later.

While at it point out that each report should focus on one issue, as
that is a good time for it: it will make the notes more straight forward
if the reader deal with multiple issues at once.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 35 +++++++++++++++-----
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 2292b79cf462..f99d92a05bca 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -617,6 +617,32 @@ should minimize it:
    look like a regression.
 
 
+Document how to reproduce issue
+-------------------------------
+
+    *Write down coarsely how to reproduce the issue. If you deal with multiple
+    issue at once, create separate notes for each of them and make sure they
+    work independently on a freshly booted system. That's needed, as each issue
+    needs to get reported to the kernel developers separately, unless they are
+    strongly entangled.*
+
+If you deal with multiple issue at once, you'll have to report each of them
+separately, as they might be handled by different developers. Describing various
+issues in one report also makes it quite difficult for others to tear it apart.
+Hence, only combine issues in one report if they are strongly entangled.
+
+Additionally, during the reporting process you will have to test if the issue
+happens with other kernel versions. Therefore, it will make your work easier if
+you know exactly how to reproduce it quickly on a freshly booted system.
+
+Note: it's often fruitless to debug issues that only happened once, as they
+might be caused by a bit flip due to cosmic radiation. That's why you should try
+to rule that out by reproducing the issue before going further. Feed free to
+ignore this if you are experienced enough to tell a one-time error due to faulty
+hardware apart from a kernel issue that rarely happens and thus is hard to
+reproduce.
+
+
 .. ############################################################################
 .. 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.
@@ -639,15 +665,6 @@ How to report Linux kernel bugs
 ===============================
 
 
-Tips for reporting bugs
------------------------
-
-It's REALLY important to report bugs that seem unrelated as separate email
-threads or separate bugzilla entries.  If you report several unrelated
-bugs at once, it's difficult for maintainers to tease apart the relevant
-data.
-
-
 Gather information
 ------------------
 
-- 
2.26.2

Re: [RFC PATCH v1 14/26] docs: reporting-bugs: make users write notes, one for each issue

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Tell users to write some rough notes how to reproduce the issue. They
> will need those notes soon once they have to reproduce the issue with
> the latest mainline kernel. At the same time they can serve as basis for
> the report later.
> 
> While at it point out that each report should focus on one issue, as
> that is a good time for it: it will make the notes more straight forward
> if the reader deal with multiple issues at once.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 35 +++++++++++++++-----
>  1 file changed, 26 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 2292b79cf462..f99d92a05bca 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -617,6 +617,32 @@ should minimize it:
>     look like a regression.
>  
>  
> +Document how to reproduce issue
> +-------------------------------
> +
> +    *Write down coarsely how to reproduce the issue. If you deal with multiple
> +    issue at once, create separate notes for each of them and make sure they

       issues

> +    work independently on a freshly booted system. That's needed, as each issue
> +    needs to get reported to the kernel developers separately, unless they are
> +    strongly entangled.*
> +
> +If you deal with multiple issue at once, you'll have to report each of them

                             issues

> +separately, as they might be handled by different developers. Describing various
> +issues in one report also makes it quite difficult for others to tear it apart.
> +Hence, only combine issues in one report if they are strongly entangled.
> +
> +Additionally, during the reporting process you will have to test if the issue
> +happens with other kernel versions. Therefore, it will make your work easier if
> +you know exactly how to reproduce it quickly on a freshly booted system.
> +
> +Note: it's often fruitless to debug issues that only happened once, as they
> +might be caused by a bit flip due to cosmic radiation. That's why you should try
> +to rule that out by reproducing the issue before going further. Feed free to

                                                                   Feel

> +ignore this if you are experienced enough to tell a one-time error due to faulty
> +hardware apart from a kernel issue that rarely happens and thus is hard to
> +reproduce.
> +
> +
>  .. ############################################################################
>  .. 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.
> @@ -639,15 +665,6 @@ How to report Linux kernel bugs
>  ===============================
>  
>  
> -Tips for reporting bugs
> ------------------------
> -
> -It's REALLY important to report bugs that seem unrelated as separate email
> -threads or separate bugzilla entries.  If you report several unrelated
> -bugs at once, it's difficult for maintainers to tease apart the relevant
> -data.
> -
> -
>  Gather information
>  ------------------
>  
> 


-- 
~Randy

Re: [RFC PATCH v1 14/26] docs: reporting-bugs: make users write notes, one for each issue

[Thorsten Leemhuis]

Am 02.10.20 um 19:35 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:

Many thx for you comments, all suggestions implemented.



Ciao, Thorsten

[RFC PATCH v1 15/26] docs: reporting-bugs: make readers test mainline, but leave a loophole

[Thorsten Leemhuis]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=yes, Size: 6884 bytes --]

Now that the document described all preparatory steps tell users to
install the latest kernel. Try pretty hard to motivate them installing a
mainline kernel, as that is best for reporting issues. Mention the
latest stable kernel as an acceptable alternative, but discourage this
option. Point out that longterm kernels are unsuitable.

While at it, provide a few hints how to obtain a fresh kernel. Also
explain how to find out what the latest version actually is. And mention
why it might be a good idea to wait till the end of the merge window
when reporting issues.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---

= RFC =

Am I asking for too much from users by telling them to test mainline? But most
will likely have an outdated and heavily patched vendor kernel anyway, so they
have to install a vanilla kernel if they want to report something upstream;
that's why I thought "well, then let's go all in and make them test mainline.
---
 Documentation/admin-guide/reporting-bugs.rst | 88 ++++++++++++++++++++
 1 file changed, 88 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index f99d92a05bca..dee6d65aa95c 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -643,6 +643,94 @@ hardware apart from a kernel issue that rarely happens and thus is hard to
 reproduce.
 
 
+Install the latest mainline kernel
+----------------------------------
+
+    *Install the latest Linux mainline kernel: that's where all issue get fixed
+    first, because it's the version line the kernel developers mainly care
+    about. Testing and reporting with the latest Linux stable kernel can be
+    acceptable alternative in some situations, but is best avoided.*
+
+Reporting an issue to the Linux kernel developers they fixed a while ago is
+annoying for them and wasting their and your time. That's why it's in
+everybody's interest to check if the issue occurs with the latest version before
+reporting it.
+
+In the scope of the Linux kernel the term 'latest' means: a kernel version
+recently created from the main line of development, as this 'mainline' tree is
+where every fix gets applied to first; only later they are allowed to get
+backported to older, still support version lines called 'stable' and 'longterm'
+kernels. That's why it's a prerequisite to check mainline even if just want to
+see the issue fixed in one of those. Another reasons: sometimes fixes for an
+issue are only applied to mainline, as they are too risky to get backported
+into older version lines where they thus remain unfixed.
+
+It's thus in your and everybody's else interest to reproduce the issue with a
+fresh mainline kernel before reporting it. Reproducing it with the latest Linux
+'stable' kernel can be acceptable alternative, if you can't test mainline for
+some reason; this is not ideal, but better than not reporting the issue at all.
+
+Avoid testing with one of the longterm kernels (sometimes called "LTS kernels"),
+they are too distant from current development; the same is also true for
+mainline or stable kernels that are not very recent, as there is a new release
+of those nearly every week.
+
+Ways to obtains a fresh vanilla kernel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One way to get the latest mainline or stable kernel in a vanilla fashion is to
+download the Linux sources from `kernel.org <https://kernel.org/>`_ and build a
+kernel image and modules from them yourself. How to do that is not described
+here, as many texts on the internet explain the necessary steps already. If you
+are new to it, consider following one of those how-to's that suggest to use
+``make localmodconfig``, as that tries to pick up the configuration of your
+current kernel and then tries to adjust it somewhat for your system. That does
+not make the resulting kernel any better, but makes it compile a lot faster.
+
+There might be a way around building your own kernel, if you are in a luck: for
+popular Linux distribution you'll find repositories on the net that offer
+packages with of the latest mainline or stable Linux vanilla kernels for easy
+installation. It's totally okay to use packages with these pre-compiled kernels,
+just make sure from the repository's documentation they are supposed to be
+'vanilla', for reasons outlined in the first step of this process. And be aware
+that you might need to build your own kernel later anyway when it comes to
+testing fixes, as described later in this document.
+
+Finding the latest Linux version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To check what the latest mainline release actually is, go to `kernel.org
+<https://kernel.org/>`_. Ignore the big yellow button that says 'Latest
+release': that points to the latest stable release, which you normally don't
+want to use.
+
+Instead, look a little lower for a table for a line with the description
+'mainline', which you'll find at the top of that table. Most of the time
+'mainline' will point to a pre-release with a version number like '5.8-rc2'. In
+that case that's the version you want to test. Do not let that 'rc' scare you,
+these 'development kernels' are pretty reliable — and you have a backup, like we
+told you above, don't you?
+
+In about two out of every nine to ten weeks, 'mainline' might point you to a
+proper release with a version number like '5.7'. If that happens consider
+suspending the reporting process for a while, as the Linux development cycle is
+currently in its two-week long 'merge window'. That's where the bulk of the
+changes (and all intrusive ones) get merged for the next release, before its
+first pre-release is published (5.8-rc1). Kernel developers are often quite
+busy during this time period and might have no spare time to deal with issue
+reports. It's also quite possible that one of the many changes applied during
+the merge window fixes the issue you face; that's why you soon would have to
+retest with a newer kernel version anyway, as outlined below in the section
+'Duties after the report when out'. Therefor it's often wise to wait for the
+first pre-release before proceeding with this step, unless you're dealing with
+one of those 'issues of high priority' or one that can't wait for a good reason.
+
+Feel free to ignore the past three paragraphs if you are a developer, Linux
+kernel expert, or brave; instead simply get the latest Linux kernel sources
+using ``git`` straight from the `official development repository on kernel.org
+<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

Re: [RFC PATCH v1 15/26] docs: reporting-bugs: make readers test mainline, but leave a loophole

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Now that the document described all preparatory steps tell users to
> install the latest kernel. Try pretty hard to motivate them installing a
> mainline kernel, as that is best for reporting issues. Mention the
> latest stable kernel as an acceptable alternative, but discourage this
> option. Point out that longterm kernels are unsuitable.
> 
> While at it, provide a few hints how to obtain a fresh kernel. Also
> explain how to find out what the latest version actually is. And mention
> why it might be a good idea to wait till the end of the merge window
> when reporting issues.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> 
> = RFC =
> 
> Am I asking for too much from users by telling them to test mainline? But most
> will likely have an outdated and heavily patched vendor kernel anyway, so they
> have to install a vanilla kernel if they want to report something upstream;
> that's why I thought "well, then let's go all in and make them test mainline.

That is appropriate IMO.

> ---
>  Documentation/admin-guide/reporting-bugs.rst | 88 ++++++++++++++++++++
>  1 file changed, 88 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index f99d92a05bca..dee6d65aa95c 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -643,6 +643,94 @@ hardware apart from a kernel issue that rarely happens and thus is hard to
>  reproduce.
>  
>  
> +Install the latest mainline kernel
> +----------------------------------
> +
> +    *Install the latest Linux mainline kernel: that's where all issue get fixed

                                                                   issues

> +    first, because it's the version line the kernel developers mainly care
> +    about. Testing and reporting with the latest Linux stable kernel can be
> +    acceptable alternative in some situations, but is best avoided.*

       an acceptable

> +
> +Reporting an issue to the Linux kernel developers they fixed a while ago is
> +annoying for them and wasting their and your time. That's why it's in
> +everybody's interest to check if the issue occurs with the latest version before
> +reporting it.
> +
> +In the scope of the Linux kernel the term 'latest' means: a kernel version
> +recently created from the main line of development, as this 'mainline' tree is
> +where every fix gets applied to first; only later they are allowed to get
> +backported to older, still support version lines called 'stable' and 'longterm'

                              supported

> +kernels. That's why it's a prerequisite to check mainline even if just want to

                                                             even if you just want to

> +see the issue fixed in one of those. Another reasons: sometimes fixes for an

                       in one of those other version lines. Another reason:


> +issue are only applied to mainline, as they are too risky to get backported
> +into older version lines where they thus remain unfixed.
> +
> +It's thus in your and everybody's else interest to reproduce the issue with a

                         everybody else's

> +fresh mainline kernel before reporting it. Reproducing it with the latest Linux
> +'stable' kernel can be acceptable alternative, if you can't test mainline for
> +some reason; this is not ideal, but better than not reporting the issue at all.
> +
> +Avoid testing with one of the longterm kernels (sometimes called "LTS kernels"),
> +they are too distant from current development; the same is also true for

   as they are too distant

> +mainline or stable kernels that are not very recent, as there is a new release
> +of those nearly every week.
> +
> +Ways to obtains a fresh vanilla kernel
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +One way to get the latest mainline or stable kernel in a vanilla fashion is to
> +download the Linux sources from `kernel.org <https://kernel.org/>`_ and build a
> +kernel image and modules from them yourself. How to do that is not described
> +here, as many texts on the internet explain the necessary steps already. If you
> +are new to it, consider following one of those how-to's that suggest to use
> +``make localmodconfig``, as that tries to pick up the configuration of your
> +current kernel and then tries to adjust it somewhat for your system. That does
> +not make the resulting kernel any better, but makes it compile a lot faster.
> +
> +There might be a way around building your own kernel, if you are in a luck: for

                                                                    in luck: for

> +popular Linux distribution you'll find repositories on the net that offer
> +packages with of the latest mainline or stable Linux vanilla kernels for easy
> +installation. It's totally okay to use packages with these pre-compiled kernels,
> +just make sure from the repository's documentation they are supposed to be
> +'vanilla', for reasons outlined in the first step of this process. And be aware
> +that you might need to build your own kernel later anyway when it comes to
> +testing fixes, as described later in this document.
> +
> +Finding the latest Linux version
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +To check what the latest mainline release actually is, go to `kernel.org
> +<https://kernel.org/>`_. Ignore the big yellow button that says 'Latest
> +release': that points to the latest stable release, which you normally don't
> +want to use.
> +
> +Instead, look a little lower for a table for a line with the description

                                            with a line with the description

> +'mainline', which you'll find at the top of that table. Most of the time
> +'mainline' will point to a pre-release with a version number like '5.8-rc2'. In
> +that case that's the version you want to test. Do not let that 'rc' scare you,
> +these 'development kernels' are pretty reliable — and you have a backup, like we
> +told you above, don't you?
> +
> +In about two out of every nine to ten weeks, 'mainline' might point you to a
> +proper release with a version number like '5.7'. If that happens consider
> +suspending the reporting process for a while, as the Linux development cycle is
> +currently in its two-week long 'merge window'. That's where the bulk of the
> +changes (and all intrusive ones) get merged for the next release, before its
> +first pre-release is published (5.8-rc1). Kernel developers are often quite
> +busy during this time period and might have no spare time to deal with issue
> +reports. It's also quite possible that one of the many changes applied during
> +the merge window fixes the issue you face; that's why you soon would have to
> +retest with a newer kernel version anyway, as outlined below in the section
> +'Duties after the report when out'. Therefor it's often wise to wait for the

                                       Therefore

> +first pre-release before proceeding with this step, unless you're dealing with
> +one of those 'issues of high priority' or one that can't wait for a good reason.
> +
> +Feel free to ignore the past three paragraphs if you are a developer, Linux
> +kernel expert, or brave; instead simply get the latest Linux kernel sources
> +using ``git`` straight from the `official development repository on kernel.org
> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_.
> +
> +
>  .. ############################################################################
>  .. 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.
> 


-- 
~Randy

Re: [RFC PATCH v1 15/26] docs: reporting-bugs: make readers test mainline, but leave a loophole

[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 02.10.20 um 19:51 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
>> = RFC =
>>
>> Am I asking for too much from users by telling them to test mainline? But most
>> will likely have an outdated and heavily patched vendor kernel anyway, so they
>> have to install a vanilla kernel if they want to report something upstream;
>> that's why I thought "well, then let's go all in and make them test mainline.
> 
> That is appropriate IMO.

Yeah, but finding the the right tone in the text seem important to me,
as some people might see it as "hey, the kernel develpers are putting
the bar really really high". That's why I pointed it out explicitly.
>> +Instead, look a little lower for a table for a line with the description
> 
>                                             with a line with the description
> 
>> +'mainline', which you'll find at the top of that table.

Rewrote this sentence:

Instead, look at the table below for a line starting with 'mainline',
which you'll find at the top of that table.

Ciao, Thorsten

Re: [RFC PATCH v1 15/26] docs: reporting-bugs: make readers test mainline, but leave a loophole

[Thorsten Leemhuis]

Am 03.10.20 um 12:11 schrieb Thorsten Leemhuis:
> Am 02.10.20 um 19:51 schrieb Randy Dunlap:
>> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
>>> = RFC =
>>>
>>> Am I asking for too much from users by telling them to test mainline? But most
>>> will likely have an outdated and heavily patched vendor kernel anyway, so they
>>> have to install a vanilla kernel if they want to report something upstream;
>>> that's why I thought "well, then let's go all in and make them test mainline.
>> That is appropriate IMO.

I'm preparing to send v2 and was a bit unhappy with this and another 
section when seeing it again after weeks. In the end I reshuffled and 
rewrote significant parts of it, see below.

Randy, would be great if you could take another look, but no pressure: 
just ignore it, if you lack the time or energy.

```
Install a fresh kernel for testing
----------------------------------

     *Install the latest Linux mainline kernel: that's where all issues 
get fixed first, because it's the version line the kernel developers 
mainly care about. Testing and reporting with the latest Linux stable 
kernel can be an acceptable alternative in some situations, for example 
during the merge window; but during that period you might want to 
suspend your efforts till its end anyway.*

Reporting an issue to the Linux kernel developers they fixed weeks or 
months ago is annoying for them and wasting their and your time. That's 
why it's in everybody's interest to check if the issue occurs with the 
latest codebase before reporting it.

In the scope of the Linux kernel the term 'latest' means: a kernel 
version recently created from the main line of development, as this 
'mainline' tree is where developer first apply fixes; only after that 
they are allowed to get backported to older, still supported version 
lines called 'stable' and 'longterm' kernels. That's why you should 
check a recent mainline kernel, even if you deal with an issue you only 
want to see fixed in an older version line. Another reason: some fixes 
are only applied to mainline or recent version lines, as it's too hard 
or risky to backport them to older versions. If that the case, reporting 
the issue again is unlikely to change anything.

Longterm kernels (sometimes called "LTS kernels") are therefore 
unsuitable for testing, they simply are too distant from current 
development. Even the latest Linux 'stable' kernel is a significant bit 
behind and thus better avoided. But sometimes it's even the right 
choice, but in those cases you might want to wait a few days before 
trying to reproduce an issue with the latest codebase:

Choosing between mainline, stable and waiting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Head over to `kernel.org <https://kernel.org/>`_ to decide which version 
to use. Ignore the big yellow button that says 'Latest release' and look 
a little lower for a table. At its top you'll see a line starting with 
'mainline', which most of the time will point to a pre-release with a 
version number like '5.8-rc2'. If that's the case, you'll want to use 
this mainline kernel for testing. Do not let that 'rc' scare you, these 
'development kernels' are pretty reliable — and you made a backup, as 
you were instructed above, don't you?

In about two out of every nine to ten weeks, 'mainline' might point you 
to a proper release with a version number like '5.7'. If that happens, 
consider suspending the reporting process until the first pre-release of 
the next version  (5.8-rc1) shows up on kernel.org. That's because the 
Linux development cycle then is in its two-week long 'merge window'. The 
bulk of the changes and all intrusive ones get merged for the next 
release during this time. It's a bit more risky to use mainline during 
this period. Kernel developers are also often quite busy then and might 
have no spare time to deal with issue reports. It's also quite possible 
that one of the many changes applied during the merge window fixes the 
issue you face; that's why you soon would have to retest with a newer 
kernel version anyway, as outlined below in the section 'Duties after 
the report when out'.

That's why it might make sense to wait till the merge window is over. 
But don't to that if you're dealing with something that shouldn't wait. 
In that case consider obtaining the latest mainline kernel via git (see 
below) or use the latest stable version offered on kernel.org. Using 
that is also acceptable in case mainline for some reason does currently 
not work for you. An in general: using it for reproducing the issue is 
also better than not reporting it issue at all.

How to obtain a fresh Linux kernel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can use pre-build or self-compiled kernel for testing; if you chose 
the latter approach, you can either obtain the source-code using git or 
download it as tar archive.

Using a pre-compiled kernel for testing is often the quickest, easiest, 
and safest way – especially is you are unfamiliar with the Linux kernel. 
But it needs to be a vanilla kernel, which can be hard to come buy. You 
are in luck if you are using a popular Linux distribution: for quite a 
few of them you'll find repositories on the net that contain packages 
with the latest mainline or stable kernels in vanilla fashion. It's 
totally okay to use these, just make sure from the repository's 
documentation they are really vanilla. And ensure the packages contain 
the latest versions as offered on kernel.org; they are likely unsuitable 
if the package is older than a week, as new mainline and stable kernels 
typically bet released at least once a week. And be aware that you might 
need to build your own kernel later anyway when it comes helping to test 
fixes, as described later in this document.

Developers and experienced Linux users familiar with git are often best 
served by obtaining the latest Linux kernel sources straight from the 
`official development repository on kernel.org 
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_. 
Those are likely a bit ahead of the latest mainline pre-release. Don't 
worry about it: they are as reliable as a proper pre-release, unless the 
kernel's development cycle is currently in the middle of a merge window. 
But even then they are quite reliable.

People unfamiliar with git are often best served by downloading the 
sources as tarball from `kernel.org <https://kernel.org/>`_.

How to actually build a kernel not described here, as many websites 
explain the necessary steps already. If you are new to it, consider 
following one of those how-to's that suggest to use ``make 
localmodconfig``, as that tries to pick up the configuration of your 
current kernel and then tries to adjust it somewhat for your system. 
That does not make the resulting kernel any better, but quicker to compile.
```

Ciao, Thorsten

Re: [RFC PATCH v1 15/26] docs: reporting-bugs: make readers test mainline, but leave a loophole

[Randy Dunlap]

On 11/11/20 7:36 AM, Thorsten Leemhuis wrote:
> Am 03.10.20 um 12:11 schrieb Thorsten Leemhuis:
>> Am 02.10.20 um 19:51 schrieb Randy Dunlap:
>>> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
>>>> = RFC =
>>>>
>>>> Am I asking for too much from users by telling them to test mainline? But most
>>>> will likely have an outdated and heavily patched vendor kernel anyway, so they
>>>> have to install a vanilla kernel if they want to report something upstream;
>>>> that's why I thought "well, then let's go all in and make them test mainline.
>>> That is appropriate IMO.
> 
> I'm preparing to send v2 and was a bit unhappy with this and another section when seeing it again after weeks. In the end I reshuffled and rewrote significant parts of it, see below.
> 
> Randy, would be great if you could take another look, but no pressure: just ignore it, if you lack the time or energy.
> 
> ```
> Install a fresh kernel for testing
> ----------------------------------
> 
>     *Install the latest Linux mainline kernel: that's where all issues get fixed first, because it's the version line the kernel developers mainly care about. Testing and reporting with the latest Linux stable kernel can be an acceptable alternative in some situations, for example during the merge window; but during that period you might want to suspend your efforts till its end anyway.*
> 
> Reporting an issue to the Linux kernel developers they fixed weeks or months ago is annoying for them and wasting their and your time. That's why it's in everybody's interest to check if the issue occurs with the latest codebase before reporting it.
> 
> In the scope of the Linux kernel the term 'latest' means: a kernel version recently created from the main line of development, as this 'mainline' tree is where developer first apply fixes; only after that they are allowed to get backported to older, still 

                              developers                   only after that are they


supported version lines called 'stable' and 'longterm' kernels. That's why you should check a recent mainline kernel, even if you deal with an issue you only want to see fixed in an older version line. Another reason: some fixes are only applied to mainline or recent version lines, as it's too hard or risky to backport them to older versions. If that the case, reporting the issue again is unlikely to change anything.
> 
> Longterm kernels (sometimes called "LTS kernels") are therefore unsuitable for testing, they simply are too distant from current 

                                                                                 testing; they
or                                                                               testing. They

development. Even the latest Linux 'stable' kernel is a significant bit behind and thus better avoided. But sometimes it's even the right choice, but in those cases you might want to wait a few days before trying to reproduce an issue with the latest codebase:

Try to remove one "But/but" in the sentence above.

> 
> Choosing between mainline, stable and waiting
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> 
> Head over to `kernel.org <https://kernel.org/>`_ to decide which version to use. Ignore the big yellow button that says 'Latest release' and look a little lower for a table. At its top you'll see a line starting with 'mainline', which most of the time will point to a pre-release with a version number like '5.8-rc2'. If that's the case, you'll want to use this mainline kernel for testing. Do not let that 'rc' scare you, these 'development kernels' are pretty reliable — and you made a backup, as you were instructed above, don't

s/don't/didn't/

 you?
> 
> In about two out of every nine to ten weeks, 'mainline' might point you to a proper release with a version number like '5.7'. If that happens, consider suspending the reporting process until the first pre-release of the next version  (5.8-rc1) shows up on 

                                                                                         only one space ^^

kernel.org. That's because the Linux development cycle then is in its two-week long 'merge window'. The bulk of the changes and all intrusive ones get merged for the next release during this time. It's a bit more risky to use mainline during this period. Kernel developers are also often quite busy then and might have no spare time to deal with issue reports. It's also quite possible that one of the many changes applied during the merge window fixes the issue you face; that's why you soon would have to retest with a newer kernel version anyway, as outlined below in the section 'Duties after the report when out'.

Should that be                                                  after the report went out'.
?

> 
> That's why it might make sense to wait till the merge window is over. But don't to that if you're dealing with something that shouldn't wait. In that case consider obtaining the latest mainline kernel via git (see below) or use the latest stable version offered on kernel.org. Using that is also acceptable in case mainline for some reason does currently not work for you. An in general: using it for reproducing the issue is also better than not reporting it issue at all.
> 
> How to obtain a fresh Linux kernel
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> 
> You can use pre-build or self-compiled kernel for testing; if you chose the latter approach, you can either obtain the source-code 

              pre-built                                             choose                                               source code

using git or download it as tar archive.
> 
> Using a pre-compiled kernel for testing is often the quickest, easiest, and safest way – especially is you are unfamiliar with the Linux kernel. But it needs to be a vanilla kernel, which can be hard to come buy. You are in luck if you are using a popular Linux distribution: for quite a few of them you'll find repositories on the net that contain packages with the latest mainline or stable kernels in vanilla fashion. It's totally okay to use these, just make sure from the repository's documentation they are really vanilla. And ensure the packages contain the latest versions as offered on kernel.org; they are likely unsuitable if the package is older than a week, as new mainline and stable kernels typically bet released at least once a week. And be aware that you might need to 

                                                                get

build your own kernel later anyway when it comes helping to test fixes, as described later in this document.

                                   when it comes to helping test fixes,

> 
> Developers and experienced Linux users familiar with git are often best served by obtaining the latest Linux kernel sources straight from the `official development repository on kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_. Those are likely a bit ahead of the latest mainline pre-release. Don't worry about it: they are as reliable as a proper pre-release, unless the kernel's development cycle is currently in the middle of a merge window. But even then they are quite reliable.
> 
> People unfamiliar with git are often best served by downloading the sources as tarball from `kernel.org <https://kernel.org/>`_.
> 
> How to actually build a kernel not described here, as many websites explain the necessary steps already. If you are new to it, 

                          kernel is not

consider following one of those how-to's that suggest to use ``make localmodconfig``, as that tries to pick up the configuration of your current kernel and then tries to adjust it somewhat for your system. That does not make the resulting kernel any better, but quicker to compile.
> ```

LGTM. Thanks.

-- 
~Randy

Re: [RFC PATCH v1 15/26] docs: reporting-bugs: make readers test mainline, but leave a loophole

[Thorsten Leemhuis]

Am 12.11.20 um 04:42 schrieb Randy Dunlap:
> On 11/11/20 7:36 AM, Thorsten Leemhuis wrote:
>> Am 03.10.20 um 12:11 schrieb Thorsten Leemhuis:
>>> Am 02.10.20 um 19:51 schrieb Randy Dunlap:
>>>> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
 > […]
>> I'm preparing to send v2 and was a bit unhappy with this and
>> another section when seeing it again after weeks. In the end I
>> reshuffled and rewrote significant parts of it, see below.
>> 
> […]

>> development. Even the latest Linux 'stable' kernel is a significant
>> bit behind and thus better avoided. But sometimes it's even the right
>> choice, but in those cases you might want to wait a few days before
>> trying to reproduce an issue with the latest codebase:
> Try to remove one "But/but" in the sentence above.

Ha, yeah, good idea. Went with this:

At least most of the time, as sometimes a stable kernel can the best 
choice; but in those situations you might want to wait a few days anyway:

> LGTM. Thanks.

Great, thx again for you feedback (Consider all the obvious spelling and
grammatical mistakes you pointed out fixed, I just didn't mention them 
here to keep the reply short)!

Ciao, Thorsten

[RFC PATCH v1 16/26] docs: reporting-bugs: let users check taint status again

[Thorsten Leemhuis]

The kernel just installed in the previous step might taint itself for
reasons unrelated to the issue the reader used when he started this
process. Make sure the reader catches this early, as this is the area
where it really matters. The former check was just ensuring the reader
notices early if his kernel is tainted, e.g. before he does more
complicated and dangerous things in this process.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index dee6d65aa95c..02f846f4a324 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -731,6 +731,19 @@ using ``git`` straight from the `official development repository on kernel.org
 <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_.
 
 
+Check 'taint' flag
+------------------
+
+    *Ensure the kernel you just installed does not 'taint' itself when running.*
+
+As outlined above in more detail already: the kernel sets a 'taint' flag when
+something happens that can lead to follow-up errors that look totally unrelated.
+That's why you need to check if the kernel you just installed does not set this
+flag. And if it does, you in almost all the cases needs to eliminate the reason
+for it before you reporting issues that occur with it. See the section above for
+details how to do that.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

[RFC PATCH v1 17/26] docs: reporting-bugs: explain options if reproducing on mainline fails

[Thorsten Leemhuis]

Explicitly lay out the remaining options if the user can't reproduce the
issue with a mainline kernel. Especially send those that are interested
in seeing it fixed in stable and longterm kernels to a section dedicated
to it (added in a later patch), as the process would get hard to follow
if all of it was explained here; especially as there is a back reference
to this process for regressions that are specific to stable and longterm
and were never present in mainline.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 02f846f4a324..2a7d13562905 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -744,6 +744,22 @@ for it before you reporting issues that occur with it. See the section above for
 details how to do that.
 
 
+Reproduce issue with the fresh kernel
+-------------------------------------
+
+    *Reproduce the issue with the kernel you just installed. If it doesn't show
+    up there, head over to the instructions for issues only happening with
+    stable and longterm kernels if you want to see it fixed there.*
+
+Check if the issue occurs with the Linux kernel you just installed. If it was
+fixed there already, consider sticking with this version line and canceling
+your plan to report the issue. But keep in mind that other users might be
+plagued by it, as long as it's not fixed in either stable and longterm version
+from kernel.org (and thus vendor kernels derived from those). If you prefer to
+use one of those and help their users, head over to the section "Details about
+reporting issues only occurring in older kernel version lines" below.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

[RFC PATCH v1 18/26] docs: reporting-bugs: let users optimize their notes

[Thorsten Leemhuis]

The reader now users the mainline kernel and is getting closer to
reporting the issue, so it's a good point to let the person recheck and
optimize the notes how to reproduce the issue. It's also a good moment
to make him search again for existing reports, as he might have learned
something in the previous steps.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 2a7d13562905..c9a3491bf4db 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -760,6 +760,26 @@ use one of those and help their users, head over to the section "Details about
 reporting issues only occurring in older kernel version lines" below.
 
 
+Optimize description to reproduce issue
+---------------------------------------
+
+    *Optimize your notes: try to find and write the most straightforward way
+    to reproduce your issue. Make sure the end result has all the important
+    details, and at the same time is easy to read and understand for others
+    that hear about it for the first time. And if you learned something in this
+    process, consider searching again for existing reports about the issue.*
+
+An unnecessarily complex report makes it quite hard for others to understand
+your report later, thus try to find a reproducer that's straight forward to
+describe and thus easy to understand in written form. Make it long enough and
+include all important details, but at the same time try to keep it as short
+as possible.
+
+In this in the previous steps you likely have learned a thing or two about the
+issue you face. Use this knowledge and search again for existing reports
+instead you can join.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

[RFC PATCH v1 19/26] docs: reporting-bugs: decode failure messages [need help]

[Thorsten Leemhuis]

This part is quite similar to the old text and just a placeholder for
now. It and the referenced document afaics need to be revisited, as they
seem outdated to me. But I'm not really familiar with the current state
of things in that area and thus didn't feel qualified to write down
anything better quickly.

So consider this a request for help for those that know this area. Could
you maybe write something that would fit in here? Or outline the current
situation roughly in a reply, as that will make it easier for me or
others to write something? It should answer questions like "when is this
actually needed", "what .config options to ideally set to make this step
easy or unnecessary?"

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index c9a3491bf4db..e1219e56979f 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -780,6 +780,18 @@ issue you face. Use this knowledge and search again for existing reports
 instead you can join.
 
 
+Decode failure messages
+-----------------------
+
+    *If the failure includes a stack dump, like an Oops does, consider decoding
+    it to find the offending line of code.*
+
+When the kernel detects an error, it will print a stack dump that allows to
+identify the exact line of code where the issue happens. But that information
+sometimes needs to get decoded to be readable, which is explained in
+admin-guide/bug-hunting.rst.
+
+
 .. ############################################################################
 .. 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.
@@ -811,9 +823,7 @@ step-by-step instructions for how a user can trigger the bug.
 
 If the failure includes an "OOPS:", take a picture of the screen, capture
 a netconsole trace, or type the message from your screen into the bug
-report.  Please read "Documentation/admin-guide/bug-hunting.rst" before posting your
-bug report. This explains what you should do with the "Oops" information
-to make it useful to the recipient.
+report.
 
 This is a suggested format for a bug report sent via email or bugzilla.
 Having a standardized bug report form makes it easier for you not to
-- 
2.26.2

[RFC PATCH v1 20/26] docs: reporting-bugs: instructions for handling regressions

[Thorsten Leemhuis]

Describe what users will have to do if they deal with a regression.
Point out that bisection is really important.

While at it explicitly mention the .config files for the newer kernel
needs to be similar to the old kernel, as that's an important detail
quite a few people seem to miss sometimes.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/bug-bisect.rst     |  2 +
 Documentation/admin-guide/reporting-bugs.rst | 53 ++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/Documentation/admin-guide/bug-bisect.rst b/Documentation/admin-guide/bug-bisect.rst
index 59567da344e8..38d9dbe7177d 100644
--- a/Documentation/admin-guide/bug-bisect.rst
+++ b/Documentation/admin-guide/bug-bisect.rst
@@ -1,3 +1,5 @@
+.. _bugbisect:
+
 Bisecting a bug
 +++++++++++++++
 
diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index e1219e56979f..71c49347c544 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -792,6 +792,59 @@ sometimes needs to get decoded to be readable, which is explained in
 admin-guide/bug-hunting.rst.
 
 
+Special care for regressions
+----------------------------
+
+    *If your problem is a regression, try to narrow down when the issue was
+    introduced as much as possible.*
+
+Linux lead developer Linus Torvalds insists that the Linux kernel never
+worsens, that's why he deems regressions as unacceptable and wants to see them
+fixed quickly. That's why changes that introduced a regression are often
+promptly reverted if the issue they cause can't get solved quickly any other
+way. Reporting a regression is thus a bit like playing a kind of trump card to
+get something quickly fixed. But for that to happen the culprit needs to be
+known. Normally it's up to the reporter to track down the change that's causing
+the regression, as maintainers often won't have the time or setup at hand to
+reproduce it themselves.
+
+To find the culprit there is a process called 'bisection' which the document
+:ref:`Documentation/admin-guide/bug-bisect.rst <bugbisect>` describes in detail.
+That process will often require you to build about ten to twenty kernel images
+and test each of them for the issue. Yes, that takes some time, but 't worry,
+it works a lot quicker than most people assume. Thanks to a 'binary search' this
+will lead you to the one commit in the source code management system that's
+causing the regression. Once you found it, serch the net for the subject of the
+change, its commit id and the shortened commit id (the first 12 characters of
+the commit id). This will lead you to exisiting reports about it, if there are
+any.
+
+Note, a bisection needs a bit of know-how, which not everyone has, and quite a
+bit of effort, which not everyone is willing to invest. Nevertheless, it's
+highly recommended performing a bisection yourself. If you really can't or don't
+want to go down that route at least find out which mainline kernel introduced
+the regression. If something for example breaks when switching from 5.5.15 to
+5.8.4, then try at least all the mainline releases in that area (5.6, 5.7 and
+5.8) to check when it first showed up. Unless you're trying to find a regression
+in a stable or longterm kernel, avoid testing versions which number has three
+sections (5.6.12, 5.7.8), as that can lead to confusion and might make your
+testing useless. Then feel free to go further in the reporting process. But
+keep in mind: if the developers will be able to help depend on the issue at
+hand. Sometimes the developers from the report will be able to recognize want
+went wrong and fix it; other times they might be unable to help unless the
+reporter performs a bisection.
+
+When dealing with regressions make sure the issue you face is really caused by
+the kernel and not by something else, as outlined above already.
+
+In the whole process keep in mind: an issue only qualifies as regression if the
+older and the newer kernel got build with a similar configuration. The best way
+to archive this: copy the configuration file (``.config``) from the old kernel
+freshly to each newer kernel version you try. Afterwards run
+``make oldnoconfig`` to adjust it for the needs of the new version without
+enabling any new feature, as those are allowed to cause regressions.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

Re: [RFC PATCH v1 20/26] docs: reporting-bugs: instructions for handling regressions

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Describe what users will have to do if they deal with a regression.
> Point out that bisection is really important.
> 
> While at it explicitly mention the .config files for the newer kernel
> needs to be similar to the old kernel, as that's an important detail
> quite a few people seem to miss sometimes.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/bug-bisect.rst     |  2 +
>  Documentation/admin-guide/reporting-bugs.rst | 53 ++++++++++++++++++++
>  2 files changed, 55 insertions(+)
> 
> diff --git a/Documentation/admin-guide/bug-bisect.rst b/Documentation/admin-guide/bug-bisect.rst
> index 59567da344e8..38d9dbe7177d 100644
> --- a/Documentation/admin-guide/bug-bisect.rst
> +++ b/Documentation/admin-guide/bug-bisect.rst
> @@ -1,3 +1,5 @@
> +.. _bugbisect:
> +
>  Bisecting a bug
>  +++++++++++++++
>  
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index e1219e56979f..71c49347c544 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -792,6 +792,59 @@ sometimes needs to get decoded to be readable, which is explained in
>  admin-guide/bug-hunting.rst.
>  
>  
> +Special care for regressions
> +----------------------------
> +
> +    *If your problem is a regression, try to narrow down when the issue was
> +    introduced as much as possible.*
> +
> +Linux lead developer Linus Torvalds insists that the Linux kernel never
> +worsens, that's why he deems regressions as unacceptable and wants to see them
> +fixed quickly. That's why changes that introduced a regression are often
> +promptly reverted if the issue they cause can't get solved quickly any other
> +way. Reporting a regression is thus a bit like playing a kind of trump card to
> +get something quickly fixed. But for that to happen the culprit needs to be
> +known. Normally it's up to the reporter to track down the change that's causing
> +the regression, as maintainers often won't have the time or setup at hand to
> +reproduce it themselves.
> +
> +To find the culprit there is a process called 'bisection' which the document
> +:ref:`Documentation/admin-guide/bug-bisect.rst <bugbisect>` describes in detail.
> +That process will often require you to build about ten to twenty kernel images
> +and test each of them for the issue. Yes, that takes some time, but 't worry,

                                                                   but don't worry,

> +it works a lot quicker than most people assume. Thanks to a 'binary search' this
> +will lead you to the one commit in the source code management system that's
> +causing the regression. Once you found it, serch the net for the subject of the

                                    find it, search

Often it can find the bad commit, but sometimes it fails. It's not always perfect.

> +change, its commit id and the shortened commit id (the first 12 characters of
> +the commit id). This will lead you to exisiting reports about it, if there are

                                         existing

> +any.
> +
> +Note, a bisection needs a bit of know-how, which not everyone has, and quite a
> +bit of effort, which not everyone is willing to invest. Nevertheless, it's
> +highly recommended performing a bisection yourself. If you really can't or don't

I would say:
   highly recommended to perform a bisection yourself.

> +want to go down that route at least find out which mainline kernel introduced
> +the regression. If something for example breaks when switching from 5.5.15 to
> +5.8.4, then try at least all the mainline releases in that area (5.6, 5.7 and
> +5.8) to check when it first showed up. Unless you're trying to find a regression
> +in a stable or longterm kernel, avoid testing versions which number has three
> +sections (5.6.12, 5.7.8), as that can lead to confusion and might make your
> +testing useless. Then feel free to go further in the reporting process. But
> +keep in mind: if the developers will be able to help depend on the issue at

                                                        depends

> +hand. Sometimes the developers from the report will be able to recognize want
> +went wrong and fix it; other times they might be unable to help unless the
> +reporter performs a bisection.
> +
> +When dealing with regressions make sure the issue you face is really caused by
> +the kernel and not by something else, as outlined above already.
> +
> +In the whole process keep in mind: an issue only qualifies as regression if the
> +older and the newer kernel got build with a similar configuration. The best way

                                  built

> +to archive this: copy the configuration file (``.config``) from the old kernel
> +freshly to each newer kernel version you try. Afterwards run
> +``make oldnoconfig`` to adjust it for the needs of the new version without
> +enabling any new feature, as those are allowed to cause regressions.
> +
> +
>  .. ############################################################################
>  .. 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.
> 


-- 
~Randy

Re: [RFC PATCH v1 20/26] docs: reporting-bugs: instructions for handling regressions

[Thorsten Leemhuis]

Many thx for you comments, all suggestions implemented.



Ciao, Thorsten

[RFC PATCH v1 21/26] docs: reporting-bugs: details on writing and sending the report

[Thorsten Leemhuis]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=yes, Size: 18164 bytes --]

Outline how to write the report. Give instructions that hopefully will
make people write better reports that ideally are also quick to evaluate
for kernel developers.

At the same time put some more faith into the readers to make them
provide all relevant data. That's a bit different to the old approach,
which told people to always send contents of files like /proc/ioports or
/proc/iomem, which in a lot of cases won't be needed and make reports
unnecessarily big.

That's also why this commit removes scripts/ver_linux as well: the
details it collects are only needed in some situations and make reports
bigger and harder to compile without good reason. Additionally, some
distributions do not ship it; a better, more modern script would likely
resist in tools/, then distros might start shipping it in packages like
"linux-tools".

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 247 +++++++++++++++----
 scripts/ver_linux                            |  81 ------
 2 files changed, 198 insertions(+), 130 deletions(-)
 delete mode 100755 scripts/ver_linux

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 71c49347c544..b06935cad880 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -845,6 +845,204 @@ freshly to each newer kernel version you try. Afterwards run
 enabling any new feature, as those are allowed to cause regressions.
 
 
+Write and send the report
+-------------------------
+
+    *Start to compile the report by writing a detailed description about the
+    issue. Always mentions a few things: the latest kernel version you installed
+    for reproducing, the Linux Distribution used, and your notes how to
+    reproduce the issue. Ideally, make the kernels build configuration (.config)
+    and the output from ``dmesg`` available somewhere on the net and link to it.
+    Include or upload all other information that might be relevant, like the
+    output/screenshot of an Oops or the output from ``lspci``. Once you wrote
+    this main part insert a normal length paragraph on top of it outlining the
+    issue and the impact quickly. On top of this add one sentence that briefly
+    describes the problem and gets people to read on. Now give the thing a
+    descriptive title or subject that yet again is shorter. Then you're ready to
+    send or file the report like the MAINTAINERS file told you, unless you are
+    dealing with one of those 'issues of high priority': they need special care
+    which is explained in 'Special handling for high priority issues' below.*
+
+Now that you have prepared everything it's time to write your report. How to do
+that is partly explained by the two documents linked to in the preface above.
+
+This text will only mention a few of the essentials as well as things apecific
+to the Linux kernel. There is one thing that fits both categories: the most
+crucial parts of your report are the title/subject, the first sentence and the
+first paragraph. Developers often get quite a lot of mail and have to quickly
+decide if one is really worth reading. Developer sometimes take just a few
+seconds to skim a mail before deciding if it's worth a closer look. Thus: the
+better the top section of your report, the higher are the chances that someone
+will look into it and help you. And that why you should ignore them for now
+and write the detailed report first. ;-)
+
+Things each report should mention
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Describe in detail how your issue happens with the fresh vanilla kernel you
+installed. Try to include the step-by-step instructions you wrote and optimized
+earlier that descibe how you and ideally others can reproduce the issue; in
+those rare cases where that's impossible try to describe what you did to trigger
+it.
+
+Also include all the relevant information others might need to understand the
+issue and its environment. What's actually needed depends a lot on the issue,
+but there are some things you should include always:
+
+ * the output from ``cat /proc/version``, which contains the Linux kernel
+   version number and the compiler it was built with.
+
+ * the Linux distribution the machine is running (``hostnamectl | grep
+   "Operating System"``)
+
+ * the architecture of the CPU and the operating system (``uname -mi``)
+
+ * if you are dealing with a regression and performed a bisection, mention the
+   subject and the commit-id of the culprit.
+
+In a lot of cases it's also wise to make two more things available to those
+that read your report:
+
+ * the configuration used for building your Linux kernel (the '.config' file)
+
+ * the kernels messages that you get from ``dmesg``. Make sure it near the top
+   contains a line like 'Linux version 5.8-1 (foobar@example.com) (gcc (GCC)
+   10.2.1, GNU ld version 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020', as
+   otherwise messages from the first boot phase are already gone from the
+   buffer. In this case instead consider using ``journalctl -b 0 -k``;
+   alternatively you can also reboot, reproduce the issue and call ``dmesg``
+   right afterwards.
+
+This data files are big, that's why it's a bad idea to put them directly into
+your report. If you are filing the issue in a bug tracker then attach them to
+the ticket. If you report the issue by mail do not attach them, as that makes
+the mail too large; instead do one of these things:
+
+ * Upload the files somewhere public (your website, a public file paste
+   service, a ticket created just for this purpose on `bugzilla.kernel.org
+   <https://bugzilla.kernel.org/>`_, ...) and include a link to them in your
+   report. Ideally use something where the files stay available for years, as
+   they could be useful to someone many years from now; this for example can
+   happen if somebody else runs into the same issue or when a developer works on
+   some code that was changed to fix your issue.
+
+ * Put the files aside and mention you will send them later in individual
+   replies to your own mail. Just remember to actually do that once the report
+   went out. ;-)
+
+Things that might be wise to provide
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Depending on the issue you might need to add more files with background data.
+Here are a few suggestions what often is good to provide:
+
+ * If you are dealing with a 'warning', an 'OOPS' or a 'panic' from the kernel,
+   include it. If you can't copy' n'paste it try to capture a netconsole trace
+   or take a picture of the screen.
+
+ * If the issue might be related to your computer hardware mention what kind of
+   system you use. If you for example have problems with your graphics card
+   mention its manufacturer and the cards model. If it's a Laptop mention its
+   name, but try to make sure it's meaningful. 'Dell XPS 13' for example is
+   not, because it might be the one from 2012; that one might look a bit similar
+   to the one sold today, but apart from that the two have nothing in common.
+   Hence, in such cases add the exact model number, which for example are
+   '9380' or '7390' for XPS 13 models introduced during 2019. Names like
+   'Lenovo Thinkpad T590' are also somewhat ambiguous: there are variants of
+   this Laptop with and without a dedicated graphics chip, so try to find the
+   exact models name or specify the main components.
+
+ * Mention the Software in the environment that's relevant. If you have
+   problems with loading modules, you want to mention the versions of kmod,
+   systemd, and udev in use. If one of the DRM drivers misbehaves, you want to
+   state the versions of libdrm and Mesa; also specify your Wayland compositor
+   or the X-Server and its driver. If you have a filesystem issue, mention the
+   version of corresponding filesystem utilities (e2fsprogs, btrfs-progs,
+   xfsprogs, …).
+
+ * Gather additional information from the kernel that might be of interest. The
+   output from ``lspci -nn`` will for example help others to identify what
+   hardware you use. If you have a problem with hardware you even might want to
+   make the output from ``sudo lspci -vvv`` available, as that provides
+   insights how the components were configured. For some issues it might be
+   good to include the contents of files like ``/proc/cpuinfo``,
+   ``/proc/ioports``, ``/proc/iomem``, ``/proc/modules``, or
+   ``/proc/scsi/scsi``. Some subsystem also offer tools to collect relevant
+   information. One such tool is ``alsa-info.sh`` `which the audio/sound
+   subsystem developers provide <https://www.alsa-project.org/wiki/AlsaInfo>`_.
+
+That will give your some ideas what data might be wise to send, but you have to
+think yourself what might be helpful for others to know. Don't worry too much
+about forgetting something: developers will ask for additional details they
+need; but making everything important available from the start increases the
+chance someone will take a closer look.
+
+The important part: the head of your report
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that you have the detailed part of the report prepared let's get back to
+the most important section: the first few sentences. Thus go to the top, add
+something like 'The detailed description:' before the part you wrote and insert
+two newlines at the top. Now write one normal length paragraph that describes
+the issue roughly. Leave out all boring details and focus on the crucial parts
+readers need to know to understand what this is all about; if you think this
+bug affects a lot of users, mention this to get people interested.
+
+Once you did that insert two more lines at the top and write a one sentence
+summary that explains quickly what the report is about. After that you have to
+get even more abstract and write an even short subject/title for the report.
+
+Now that you have written this part take some time to optimize it, as it is the
+most important parts of your report: a lot of people will only read this before
+they decide if reading the rest is time well spend.
+
+Now send or file the report like the `MAINTAINERS file
+<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
+told you, unless it's one of those 'issues of high priority' outlined earlier:
+In that read the next subsection before sending the report.
+
+Special handling for high priority issues
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+High priority issues need special handling when sending the report:
+
+
+ * *Regression* If the issue is a regression add [REGRESSION] to the mails
+   subject or the title in the bug-tracker. If you did not perform a bisection
+   mention at least the latest mainline version you tested that worked fine (say
+   5.7) and the oldest where the issue occurs (say 5.8). If you did a successful
+   bisection mention the commit id and subject of the change that causes the
+   regression. Also make sure to add the author of that change to your report;
+   if you need to file your bug in a bug-tracker forward the report to him in a
+   private mail and mention where your filed it.
+
+ * *Severe bug*: make sure the subject or ticket title as well as the first para
+   makes the severeness obvious.
+
+ * *Security issues*: for these issues your will have to evaluate if a
+   short-term risk to other users would arise if details were publicly
+   disclosed. If that's not the case simply proceed with reporting the issue as
+   described. For issues that bear such a risk you will need to adjust the
+   reporting process slightly:
+
+   * If the MAINTAINERS file instructed you to report the issue by mail, do not
+     CC any public mailing lists.
+
+   * If you were supposed to file the issue in a bug tracker make sure to mark
+     the ticket as 'private' or 'security issue'. If the bug tracker does not
+     offer a way to keep reports private, forget about it and send your report
+     as a private mail to the maintainers instead.
+
+   In both cases make sure to inform those that the MAINTAINERS file lists in
+   the section 'security contact'. Ideally CCing them on the mail with the
+   report. If you filed it in a bug tracker forward the reports text, but on top
+   of it put a small note where you mention that you filed it with a link to the
+   ticket.
+
+   See :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` for more
+   information.
+
+
 .. ############################################################################
 .. 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.
@@ -867,55 +1065,6 @@ How to report Linux kernel bugs
 ===============================
 
 
-Gather information
-------------------
-
-The most important information in a bug report is how to reproduce the
-bug.  This includes system information, and (most importantly)
-step-by-step instructions for how a user can trigger the bug.
-
-If the failure includes an "OOPS:", take a picture of the screen, capture
-a netconsole trace, or type the message from your screen into the bug
-report.
-
-This is a suggested format for a bug report sent via email or bugzilla.
-Having a standardized bug report form makes it easier for you not to
-overlook things, and easier for the developers to find the pieces of
-information they're really interested in.  If some information is not
-relevant to your bug, feel free to exclude it.
-
-First run the ver_linux script included as scripts/ver_linux, which
-reports the version of some important subsystems.  Run this script with
-the command ``awk -f scripts/ver_linux``.
-
-Use that information to fill in all fields of the bug report form, and
-post it to the mailing list with a subject of "PROBLEM: <one line
-summary from [1.]>" for easy identification by the developers::
-
-  [1.] One line summary of the problem:
-  [2.] Full description of the problem/report:
-  [3.] Keywords (i.e., modules, networking, kernel):
-  [4.] Kernel information
-  [4.1.] Kernel version (from /proc/version):
-  [4.2.] Kernel .config file:
-  [5.] Most recent kernel version which did not have the bug:
-  [6.] Output of Oops.. message (if applicable) with symbolic information
-       resolved (see Documentation/admin-guide/bug-hunting.rst)
-  [7.] A small shell script or example program which triggers the
-       problem (if possible)
-  [8.] Environment
-  [8.1.] Software (add the output of the ver_linux script here)
-  [8.2.] Processor information (from /proc/cpuinfo):
-  [8.3.] Module information (from /proc/modules):
-  [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem)
-  [8.5.] PCI information ('lspci -vvv' as root)
-  [8.6.] SCSI information (from /proc/scsi/scsi)
-  [8.7.] Other information that might be relevant to the problem
-         (please look in /proc and include all information that you
-         think to be relevant):
-  [X.] Other notes, patches, fixes, workarounds:
-
-
 Follow up
 =========
 
diff --git a/scripts/ver_linux b/scripts/ver_linux
deleted file mode 100755
index 0968a3070eff..000000000000
--- a/scripts/ver_linux
+++ /dev/null
@@ -1,81 +0,0 @@
-#!/usr/bin/awk -f
-# SPDX-License-Identifier: GPL-2.0
-# Before running this script please ensure that your PATH is
-# typical as you use for compilation/installation. I use
-# /bin /sbin /usr/bin /usr/sbin /usr/local/bin, but it may
-# differ on your system.
-
-BEGIN {
-	usage = "If some fields are empty or look unusual you may have an old version.\n"
-	usage = usage "Compare to the current minimal requirements in Documentation/Changes.\n"
-	print usage
-
-	system("uname -a")
-	printf("\n")
-
-	vernum = "[0-9]+([.]?[0-9]+)+"
-	libc = "libc[.]so[.][0-9]+$"
-	libcpp = "(libg|stdc)[+]+[.]so[.][0-9]+$"
-
-	printversion("GNU C", version("gcc -dumpversion"))
-	printversion("GNU Make", version("make --version"))
-	printversion("Binutils", version("ld -v"))
-	printversion("Util-linux", version("mount --version"))
-	printversion("Mount", version("mount --version"))
-	printversion("Module-init-tools", version("depmod -V"))
-	printversion("E2fsprogs", version("tune2fs"))
-	printversion("Jfsutils", version("fsck.jfs -V"))
-	printversion("Reiserfsprogs", version("reiserfsck -V"))
-	printversion("Reiser4fsprogs", version("fsck.reiser4 -V"))
-	printversion("Xfsprogs", version("xfs_db -V"))
-	printversion("Pcmciautils", version("pccardctl -V"))
-	printversion("Pcmcia-cs", version("cardmgr -V"))
-	printversion("Quota-tools", version("quota -V"))
-	printversion("PPP", version("pppd --version"))
-	printversion("Isdn4k-utils", version("isdnctrl"))
-	printversion("Nfs-utils", version("showmount --version"))
-	printversion("Bison", version("bison --version"))
-	printversion("Flex", version("flex --version"))
-
-	while ("ldconfig -p 2>/dev/null" | getline > 0) {
-		if ($NF ~ libc && !seen[ver = version("readlink " $NF)]++)
-			printversion("Linux C Library", ver)
-		else if ($NF ~ libcpp && !seen[ver = version("readlink " $NF)]++)
-			printversion("Linux C++ Library", ver)
-	}
-
-	printversion("Dynamic linker (ldd)", version("ldd --version"))
-	printversion("Procps", version("ps --version"))
-	printversion("Net-tools", version("ifconfig --version"))
-	printversion("Kbd", version("loadkeys -V"))
-	printversion("Console-tools", version("loadkeys -V"))
-	printversion("Oprofile", version("oprofiled --version"))
-	printversion("Sh-utils", version("expr --v"))
-	printversion("Udev", version("udevadm --version"))
-	printversion("Wireless-tools", version("iwconfig --version"))
-
-	while ("sort /proc/modules" | getline > 0) {
-		mods = mods sep $1
-		sep = " "
-	}
-	printversion("Modules Loaded", mods)
-}
-
-function version(cmd,    ver) {
-	cmd = cmd " 2>&1"
-	while (cmd | getline > 0) {
-		if (match($0, vernum)) {
-			ver = substr($0, RSTART, RLENGTH)
-			break
-		}
-	}
-	close(cmd)
-	return ver
-}
-
-function printversion(name, value,  ofmt) {
-	if (value != "") {
-		ofmt = "%-20s\t%s\n"
-		printf(ofmt, name, value)
-	}
-}
-- 
2.26.2

Re: [RFC PATCH v1 21/26] docs: reporting-bugs: details on writing and sending the report

[Randy Dunlap]

On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:
> Outline how to write the report. Give instructions that hopefully will
> make people write better reports that ideally are also quick to evaluate
> for kernel developers.
> 
> At the same time put some more faith into the readers to make them
> provide all relevant data. That's a bit different to the old approach,
> which told people to always send contents of files like /proc/ioports or
> /proc/iomem, which in a lot of cases won't be needed and make reports
> unnecessarily big.
> 
> That's also why this commit removes scripts/ver_linux as well: the
> details it collects are only needed in some situations and make reports
> bigger and harder to compile without good reason. Additionally, some
> distributions do not ship it; a better, more modern script would likely
> resist in tools/, then distros might start shipping it in packages like
> "linux-tools".
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 247 +++++++++++++++----
>  scripts/ver_linux                            |  81 ------
>  2 files changed, 198 insertions(+), 130 deletions(-)
>  delete mode 100755 scripts/ver_linux
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 71c49347c544..b06935cad880 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -845,6 +845,204 @@ freshly to each newer kernel version you try. Afterwards run
>  enabling any new feature, as those are allowed to cause regressions.
>  
>  
> +Write and send the report
> +-------------------------
> +
> +    *Start to compile the report by writing a detailed description about the
> +    issue. Always mentions a few things: the latest kernel version you installed

                     mention

> +    for reproducing, the Linux Distribution used, and your notes how to

                                                              notes {of,on} how to

> +    reproduce the issue. Ideally, make the kernels build configuration (.config)

                                              kernel's

> +    and the output from ``dmesg`` available somewhere on the net and link to it.
> +    Include or upload all other information that might be relevant, like the
> +    output/screenshot of an Oops or the output from ``lspci``. Once you wrote
> +    this main part insert a normal length paragraph on top of it outlining the
> +    issue and the impact quickly. On top of this add one sentence that briefly
> +    describes the problem and gets people to read on. Now give the thing a
> +    descriptive title or subject that yet again is shorter. Then you're ready to
> +    send or file the report like the MAINTAINERS file told you, unless you are
> +    dealing with one of those 'issues of high priority': they need special care
> +    which is explained in 'Special handling for high priority issues' below.*
> +
> +Now that you have prepared everything it's time to write your report. How to do
> +that is partly explained by the two documents linked to in the preface above.
> +
> +This text will only mention a few of the essentials as well as things apecific

                                                                         specific

> +to the Linux kernel. There is one thing that fits both categories: the most
> +crucial parts of your report are the title/subject, the first sentence and the
> +first paragraph. Developers often get quite a lot of mail and have to quickly
> +decide if one is really worth reading. Developer sometimes take just a few
> +seconds to skim a mail before deciding if it's worth a closer look. Thus: the
> +better the top section of your report, the higher are the chances that someone
> +will look into it and help you. And that why you should ignore them for now

                                       that is why

> +and write the detailed report first. ;-)
> +
> +Things each report should mention
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Describe in detail how your issue happens with the fresh vanilla kernel you
> +installed. Try to include the step-by-step instructions you wrote and optimized
> +earlier that descibe how you and ideally others can reproduce the issue; in

                describe

> +those rare cases where that's impossible try to describe what you did to trigger
> +it.
> +
> +Also include all the relevant information others might need to understand the
> +issue and its environment. What's actually needed depends a lot on the issue,
> +but there are some things you should include always:
> +
> + * the output from ``cat /proc/version``, which contains the Linux kernel
> +   version number and the compiler it was built with.
> +
> + * the Linux distribution the machine is running (``hostnamectl | grep
> +   "Operating System"``)
> +
> + * the architecture of the CPU and the operating system (``uname -mi``)
> +
> + * if you are dealing with a regression and performed a bisection, mention the
> +   subject and the commit-id of the culprit.
> +
> +In a lot of cases it's also wise to make two more things available to those
> +that read your report:
> +
> + * the configuration used for building your Linux kernel (the '.config' file)
> +
> + * the kernels messages that you get from ``dmesg``. Make sure it near the top

          kernel's                                      Make sure that it contains
a line lie ' ... ' near the top; otherwise messages


> +   contains a line like 'Linux version 5.8-1 (foobar@example.com) (gcc (GCC)
> +   10.2.1, GNU ld version 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020', as
> +   otherwise messages from the first boot phase are already gone from the
> +   buffer. In this case instead consider using ``journalctl -b 0 -k``;
> +   alternatively you can also reboot, reproduce the issue and call ``dmesg``
> +   right afterwards.
> +
> +This data files are big, that's why it's a bad idea to put them directly into

   This data file is big; that's why

> +your report. If you are filing the issue in a bug tracker then attach them to
> +the ticket. If you report the issue by mail do not attach them, as that makes
> +the mail too large; instead do one of these things:
> +
> + * Upload the files somewhere public (your website, a public file paste
> +   service, a ticket created just for this purpose on `bugzilla.kernel.org
> +   <https://bugzilla.kernel.org/>`_, ...) and include a link to them in your
> +   report. Ideally use something where the files stay available for years, as
> +   they could be useful to someone many years from now; this for example can
> +   happen if somebody else runs into the same issue or when a developer works on
> +   some code that was changed to fix your issue.
> +
> + * Put the files aside and mention you will send them later in individual
> +   replies to your own mail. Just remember to actually do that once the report
> +   went out. ;-)
> +
> +Things that might be wise to provide
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Depending on the issue you might need to add more files with background data.
> +Here are a few suggestions what often is good to provide:
> +
> + * If you are dealing with a 'warning', an 'OOPS' or a 'panic' from the kernel,
> +   include it. If you can't copy' n'paste it try to capture a netconsole trace

                  If you can't copy'n'paste it, try

> +   or take a picture of the screen.
> +
> + * If the issue might be related to your computer hardware mention what kind of

                                                     hardware, mention

> +   system you use. If you for example have problems with your graphics card

                                                                          card,

> +   mention its manufacturer and the cards model. If it's a Laptop mention its

                                       card's                 laptop,


> +   name, but try to make sure it's meaningful. 'Dell XPS 13' for example is
> +   not, because it might be the one from 2012; that one might look a bit similar
> +   to the one sold today, but apart from that the two have nothing in common.
> +   Hence, in such cases add the exact model number, which for example are
> +   '9380' or '7390' for XPS 13 models introduced during 2019. Names like
> +   'Lenovo Thinkpad T590' are also somewhat ambiguous: there are variants of
> +   this Laptop with and without a dedicated graphics chip, so try to find the

           laptop

> +   exact models name or specify the main components.

            model's
or          model name

> +
> + * Mention the Software in the environment that's relevant. If you have
> +   problems with loading modules, you want to mention the versions of kmod,
> +   systemd, and udev in use. If one of the DRM drivers misbehaves, you want to
> +   state the versions of libdrm and Mesa; also specify your Wayland compositor
> +   or the X-Server and its driver. If you have a filesystem issue, mention the

             X Server

> +   version of corresponding filesystem utilities (e2fsprogs, btrfs-progs,
> +   xfsprogs, …).

Can we try to use ASCII as much as possible (for text/console readability)?
So just "...".

> +
> + * Gather additional information from the kernel that might be of interest. The
> +   output from ``lspci -nn`` will for example help others to identify what
> +   hardware you use. If you have a problem with hardware you even might want to
> +   make the output from ``sudo lspci -vvv`` available, as that provides
> +   insights how the components were configured. For some issues it might be
> +   good to include the contents of files like ``/proc/cpuinfo``,
> +   ``/proc/ioports``, ``/proc/iomem``, ``/proc/modules``, or
> +   ``/proc/scsi/scsi``. Some subsystem also offer tools to collect relevant
> +   information. One such tool is ``alsa-info.sh`` `which the audio/sound
> +   subsystem developers provide <https://www.alsa-project.org/wiki/AlsaInfo>`_.
> +
> +That will give your some ideas what data might be wise to send, but you have to

                            ideas of what data

> +think yourself what might be helpful for others to know. Don't worry too much
> +about forgetting something: developers will ask for additional details they
> +need; but making everything important available from the start increases the
> +chance someone will take a closer look.
> +
> +The important part: the head of your report
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Now that you have the detailed part of the report prepared let's get back to
> +the most important section: the first few sentences. Thus go to the top, add
> +something like 'The detailed description:' before the part you wrote and insert
> +two newlines at the top. Now write one normal length paragraph that describes
> +the issue roughly. Leave out all boring details and focus on the crucial parts
> +readers need to know to understand what this is all about; if you think this
> +bug affects a lot of users, mention this to get people interested.
> +
> +Once you did that insert two more lines at the top and write a one sentence
> +summary that explains quickly what the report is about. After that you have to
> +get even more abstract and write an even short subject/title for the report.

                                            shorter

> +
> +Now that you have written this part take some time to optimize it, as it is the
> +most important parts of your report: a lot of people will only read this before
> +they decide if reading the rest is time well spend.

                                                spent.

> +
> +Now send or file the report like the `MAINTAINERS file
> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
> +told you, unless it's one of those 'issues of high priority' outlined earlier:
> +In that read the next subsection before sending the report.
> +
> +Special handling for high priority issues
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +High priority issues need special handling when sending the report:
> +
> +
> + * *Regression* If the issue is a regression add [REGRESSION] to the mails

                                                                        mail's

> +   subject or the title in the bug-tracker. If you did not perform a bisection
> +   mention at least the latest mainline version you tested that worked fine (say
> +   5.7) and the oldest where the issue occurs (say 5.8). If you did a successful
> +   bisection mention the commit id and subject of the change that causes the
> +   regression. Also make sure to add the author of that change to your report;
> +   if you need to file your bug in a bug-tracker forward the report to him in a
> +   private mail and mention where your filed it.
> +
> + * *Severe bug*: make sure the subject or ticket title as well as the first para

                                                                               paragraph

> +   makes the severeness obvious.
> +
> + * *Security issues*: for these issues your will have to evaluate if a
> +   short-term risk to other users would arise if details were publicly
> +   disclosed. If that's not the case simply proceed with reporting the issue as
> +   described. For issues that bear such a risk you will need to adjust the
> +   reporting process slightly:
> +
> +   * If the MAINTAINERS file instructed you to report the issue by mail, do not
> +     CC any public mailing lists.
> +
> +   * If you were supposed to file the issue in a bug tracker make sure to mark
> +     the ticket as 'private' or 'security issue'. If the bug tracker does not
> +     offer a way to keep reports private, forget about it and send your report
> +     as a private mail to the maintainers instead.
> +
> +   In both cases make sure to inform those that the MAINTAINERS file lists in
> +   the section 'security contact'. Ideally CCing them on the mail with the
> +   report. If you filed it in a bug tracker forward the reports text, but on top

parse error in first 2 sentences above...
                                                           report's

> +   of it put a small note where you mention that you filed it with a link to the
> +   ticket.
> +
> +   See :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` for more
> +   information.
> +
> +
>  .. ############################################################################
>  .. 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.
> @@ -867,55 +1065,6 @@ How to report Linux kernel bugs
>  ===============================
>  
>  
> -Gather information
> -------------------
> -
> -The most important information in a bug report is how to reproduce the
> -bug.  This includes system information, and (most importantly)
> -step-by-step instructions for how a user can trigger the bug.
> -
> -If the failure includes an "OOPS:", take a picture of the screen, capture
> -a netconsole trace, or type the message from your screen into the bug
> -report.
> -
> -This is a suggested format for a bug report sent via email or bugzilla.
> -Having a standardized bug report form makes it easier for you not to
> -overlook things, and easier for the developers to find the pieces of
> -information they're really interested in.  If some information is not
> -relevant to your bug, feel free to exclude it.
> -
> -First run the ver_linux script included as scripts/ver_linux, which
> -reports the version of some important subsystems.  Run this script with
> -the command ``awk -f scripts/ver_linux``.
> -
> -Use that information to fill in all fields of the bug report form, and
> -post it to the mailing list with a subject of "PROBLEM: <one line
> -summary from [1.]>" for easy identification by the developers::
> -
> -  [1.] One line summary of the problem:
> -  [2.] Full description of the problem/report:
> -  [3.] Keywords (i.e., modules, networking, kernel):
> -  [4.] Kernel information
> -  [4.1.] Kernel version (from /proc/version):
> -  [4.2.] Kernel .config file:
> -  [5.] Most recent kernel version which did not have the bug:
> -  [6.] Output of Oops.. message (if applicable) with symbolic information
> -       resolved (see Documentation/admin-guide/bug-hunting.rst)
> -  [7.] A small shell script or example program which triggers the
> -       problem (if possible)
> -  [8.] Environment
> -  [8.1.] Software (add the output of the ver_linux script here)
> -  [8.2.] Processor information (from /proc/cpuinfo):
> -  [8.3.] Module information (from /proc/modules):
> -  [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem)
> -  [8.5.] PCI information ('lspci -vvv' as root)
> -  [8.6.] SCSI information (from /proc/scsi/scsi)
> -  [8.7.] Other information that might be relevant to the problem
> -         (please look in /proc and include all information that you
> -         think to be relevant):
> -  [X.] Other notes, patches, fixes, workarounds:
> -
> -
>  Follow up
>  =========
>  


-- 
~Randy

Re: [RFC PATCH v1 21/26] docs: reporting-bugs: details on writing and sending the 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 09.10.20 um 04:45 schrieb Randy Dunlap:
> On 10/1/20 1:39 AM, Thorsten Leemhuis wrote:

>> +   In both cases make sure to inform those that the MAINTAINERS file lists in
>> +   the section 'security contact'. Ideally CCing them on the mail with the
>> +   report. If you filed it in a bug tracker forward the reports text, but on top
> 
> parse error in first 2 sentences above...

Now reads:

In both cases make sure to mail your report to the addresses the 
MAINTAINERS file lists in the section 'security contact'. Ideally 
directly CC them when sending the report by mail.

Ciao, Thorsten

[RFC PATCH v1 22/26] docs: reporting-bugs: explain what users should do once the report got out

[Thorsten Leemhuis]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=yes, Size: 14360 bytes --]

Users should know that sending the report is not the end of this
process: if want to see the issue fixed, they will need to keep the ball
rolling sometimes. Hence, explain why it's in their interest to send a
reminder occasionally. Als point out that it's a really good idea to
retest shortly after the rc1 of a new mainline release came out.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---

= RFC =

This commit removes a section from the old text that kinda tells maintainers
what users can expect from them. Should this be made more explicit in the Kernel
Maintainer Handbook? Maybe something along the lines of "Try to answer each
issue report at least once, ideally within 1 to 5 business days"?
---
 Documentation/admin-guide/reporting-bugs.rst | 222 +++++++++++++++----
 1 file changed, 180 insertions(+), 42 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index b06935cad880..b8bc6c4e2340 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -1043,6 +1043,186 @@ High priority issues need special handling when sending the report:
    information.
 
 
+Duties after the report went out
+--------------------------------
+
+    *Wait for reactions and keep the thing rolling until you can accept the
+    outcome in one way or the other. Thus react publicly and in a timely manner
+    to any inquiries. Test proposed fixes. Do proactive testing when a new rc1
+    gets released. Sent friendly reminders if things stall. And try to help
+    yourself, if you don't get any help or if it is unsatisfying.*
+
+If your report was good and you are really lucky then one of the developers
+might immediately spot what's causing the issue; then he might write a patch to
+fix it, test it, and sends it straight for integration in mainline while
+tagging it for later backport to stable and longterm kernels that need it. Then
+all you need to do is reply with a 'Thank you very much' and switch to a
+version with the fix once it gets released.
+
+But this ideal scenario rarely happens, that's why the job is only starting once
+you got the report out. What you'll have to do depends on the issue, but often
+it will be the things listed below. But before digging into the details a few
+important things you need to keep in mind for this part of the process.
+
+General advice for further interactions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Always reply in public*: When the issue was filed in a bug tracker always
+reply there and do not contact any of the developer privately about it. For
+mailed reports always use the 'Reply-all' function when replying to any mails
+you receive. That includes mails with any additional data you might want to add
+to your report: go to your mail applications 'Sent' folder and use 'reply-all'
+on your mail with the report. This approach will make sure the public mailing
+list(s) and everyone else that gets involved over time always stays in the
+loop; it also keeps the mail thread intact, which among others is really
+important for mailing list to group all related mails together.
+
+There are just two situations where a comment in a bug tracker or a 'Reply-all'
+is unsuitable:
+
+ * Someone tells you to send something privately.
+
+ * You were told to sent something, but noticed it contains sensitive
+   information that really needs to be kept private. In that case it's okay to
+   sent it in private to the developer that asked for it. But point in the
+   ticket or a mail that you did that, so everyone else knows the request was
+   honored.
+
+*Do research before asking for clarifications or help*: In this part of the
+process someone might tell you to do something that requires a skill you might
+not have mastered yet. For example, you might get ask to use some test tools
+you never have heard of yet; or you might get asked to apply a patch to the
+Linux kernel sources to test if it helps. In some cases it will be fine sending
+a reply asking for instructions how to do that. But before going that route try
+to find the answer own your own by searching the internet; alternatively
+consider asking a friend or in some chatroom/forum you normally hang out for
+advice.
+
+*Be patient*: If you are really lucky you might get a reply to your report
+within a few hours. But most of the time it will take longer, as maintainers
+are scattered around the globe and thus might be in a different time zone – one
+where they already enjoy their evening away from keyboard.
+
+In general, kernel developers will take one to five business days to respond to
+reports. Sometimes it will take longer, as they might be busy with other work,
+visiting developer conferences, or simply enjoying a long summer holiday.
+
+The 'issues of high priority' (see above for an explanation) are an exception
+here: maintainer should address them as soon as possible, that's why you should
+wait a week at maximum (or just two days if it's something urgent) before
+sending a friendly reminder. If the maintainer is not responding in a timely
+manner or not handing it appropriately, mention that you are considering to
+escalate the issue to a higher authority and do so if there is in the end
+there seems to be no way around this. In case of Wi-Fi driver code you for
+example would escalate it to the wireless maintainers; if there are no higher
+level maintainers or all else fails it might be one of those situations where
+it's okay to get Linus Torvalds involved directly.
+
+*Proactive testing*: Every time the first pre-release (the 'rc1') of a new
+mainline kernel version gets released, go and check if the issue is fixed there
+or if anything of importance changed. Mention the outcome in the ticket or in a
+reply to the report (make sure it has all those in the CC that up to that point
+participated in the discussion). This will show your commitment and that you
+are willing to help. It also tells developers if the issue persists and makes
+sure they do not forget about it. A few other occasional retests (for example
+with rc3, rc6 and the final) are also a good idea, but only report your results
+if something relevant changed or if you are writing something anyway.
+
+With all these general things off the table let's get into the details how to
+help to get issues resolved once they were reported.
+
+Inquires and testing request
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here are your duties in case you got replies to your report:
+
+ *Check who you deal with*: Most of the time it will be the maintainer or a
+ developer of the particular code area that will respond to your report. But as
+ issues are normally reported in public it could be anyone that's replying —
+ including people that want to help, but in the end might guide you totally off
+ track with their questions or requests. That rarely happens, but it's one of
+ many reasons why it's wise to quickly run an internet search to see who you're
+ interacting with. You also get aware if your report was heard by the right
+ people, as a reminder to the maintainer (see below) might be in order later if
+ discussion fades out and does not lead to a fix.
+
+ *Inquires for data*: Often you will be asked to test something or provide
+ additional details. Try to provide the information requested soon, as you have
+ the attention of someone that might help and risk losing it the longer you
+ wait; that outcome is even likely if you do not provide the information within
+ a few business days.
+
+ *Requests for testing*: When you get asked to test a diagnostic patch or a
+ possible fix try to test it in timely manner, too. Do it properly and make
+ sure to not rush it: mixing things up can happen easily and lead to a lot
+ of confusion for everyone involved. A common mistake for example is thinking a
+ kernel patch that might fix the issue was applied, but in fact wasn't – even
+ experienced testers make such mistakes occasionally and only notice when the
+ kernel built from those sources behaves just as before.
+
+What to do when nothing of substance happens
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some report will not get any reaction from the responsible Linux kernel
+developers; or a discussion around the issue evolved, but it faded out and
+nothing of substance came out of it.
+
+In these cases wait two (better: three) weeks before sending a friendly
+reminder: maybe the maintainer was just away from keyboard for a while when
+your report arrived or had something more important to take care of. When
+writing the reminder, kindly ask if anything else from your side is needed to
+get the ball running somehow. If the report got out by mail do that in the first
+lines of a mail that is a reply to your initial mail (see above) which includes
+a full quote of the original report below: that's on of those few situations
+where such a 'TOFU' (Text Over, Fullquote Under) is the right approach, as then
+all the recipients will have the details at hand immediately in the proper
+order.
+
+After the reminder wait three more weeks for replies. If you still don't get a
+proper reaction, you first should reconsider your approach. Did you maybe try
+to reach out to the wrong people? Was the report maybe offensive or so
+confusing that people decided to completely stay away from it? The best way to
+rule out such factors: show the report to one or two people familiar with FLOSS
+issue reporting and ask for their option. Also ask them for their advice how to
+move forward. That might mean: prepare a better report and make those people
+review it before you sent it out. Such an approach it totally fine, just
+mentions that this is the second and improved report on the issue and include a
+link to the first report.
+
+If the report was proper you can send a second reminder; in it ask for advice
+why the report did not get any replies. A good moment for this second reminder
+mail is shortly after the first pre-release (the 'rc1') of a new Linux kernel
+version got published, as you should retest at that point anyway (see above).
+
+If the second reminder again results in no reaction within a week, try to
+contact a higher-level maintainer asking for advice: even busy maintainers by
+then should at least have sent some kind of acknowledgment.
+
+Remember to prepare yourself for a disappointment: maintainers ideally should
+react somehow to every issue report, but they are only obliged to fix those
+'issues of high priority' outlined earlier. So don't be too devastating if you
+get a  reply along the lines of 'thanks for the report, I have more important
+issues to deal with currently and won't have time to look into this for the
+foreseeable future'.
+
+It's also possible that after some discussion in the bug tracker or one a list
+nothing happens anymore and reminders don't help to motivate anyone to work out
+a fix. Such situations can be devastating, but is within the cards when if
+comes to Linux kernel development. This and sore other reasons for not getting
+help are explained in 'Why some issues won't get any reaction or remain unfixed
+after being reported' near the end of this document.
+
+Don't get devastated if you don't get any help or if the issue in the end does
+not get solved: as this the Linux kernel is FLOSS and thus you can still help
+yourself. Find others that are affected and try to team up with them to get the
+issue resolved. You for example can prepare a fresh report together that
+mentions how many you are and why this is something that in your option should
+get fixed. Maybe together you can also narrow down the root cause or the change
+that introduced a regression, which often makes developing a fix easier. And
+with a bit of luck there might be someone in the team that knows a bit about
+programming and might be able to write a fix.
+
+
 .. ############################################################################
 .. 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.
@@ -1064,48 +1244,6 @@ backported to it.
 How to report Linux kernel bugs
 ===============================
 
-
-Follow up
-=========
-
-Expectations for bug reporters
-------------------------------
-
-Linux kernel maintainers expect bug reporters to be able to follow up on
-bug reports.  That may include running new tests, applying patches,
-recompiling your kernel, and/or re-triggering your bug.  The most
-frustrating thing for maintainers is for someone to report a bug, and then
-never follow up on a request to try out a fix.
-
-That said, it's still useful for a kernel maintainer to know a bug exists
-on a supported kernel, even if you can't follow up with retests.  Follow
-up reports, such as replying to the email thread with "I tried the latest
-kernel and I can't reproduce my bug anymore" are also helpful, because
-maintainers have to assume silence means things are still broken.
-
-Expectations for kernel maintainers
------------------------------------
-
-Linux kernel maintainers are busy, overworked human beings.  Some times
-they may not be able to address your bug in a day, a week, or two weeks.
-If they don't answer your email, they may be on vacation, or at a Linux
-conference.  Check the conference schedule at https://LWN.net for more info:
-
-	https://lwn.net/Calendar/
-
-In general, kernel maintainers take 1 to 5 business days to respond to
-bugs.  The majority of kernel maintainers are employed to work on the
-kernel, and they may not work on the weekends.  Maintainers are scattered
-around the world, and they may not work in your time zone.  Unless you
-have a high priority bug, please wait at least a week after the first bug
-report before sending the maintainer a reminder email.
-
-The exceptions to this rule are regressions, kernel crashes, security holes,
-or userspace breakage caused by new kernel behavior.  Those bugs should be
-addressed by the maintainers ASAP.  If you suspect a maintainer is not
-responding to these types of bugs in a timely manner (especially during a
-merge window), escalate the bug to LKML and Linus Torvalds.
-
 Thank you!
 
 [Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]
-- 
2.26.2

Re: [RFC PATCH v1 22/26] docs: reporting-bugs: explain what users should do once the report got out

[Randy Dunlap]

On 10/1/20 1:50 AM, Thorsten Leemhuis wrote:
> Users should know that sending the report is not the end of this
> process: if want to see the issue fixed, they will need to keep the ball
> rolling sometimes. Hence, explain why it's in their interest to send a
> reminder occasionally. Als point out that it's a really good idea to
> retest shortly after the rc1 of a new mainline release came out.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
> 
> = RFC =
> 
> This commit removes a section from the old text that kinda tells maintainers
> what users can expect from them. Should this be made more explicit in the Kernel
> Maintainer Handbook? Maybe something along the lines of "Try to answer each
> issue report at least once, ideally within 1 to 5 business days"?
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 222 +++++++++++++++----
>  1 file changed, 180 insertions(+), 42 deletions(-)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index b06935cad880..b8bc6c4e2340 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -1043,6 +1043,186 @@ High priority issues need special handling when sending the report:
>     information.
>  
>  
> +Duties after the report went out
> +--------------------------------
> +
> +    *Wait for reactions and keep the thing rolling until you can accept the
> +    outcome in one way or the other. Thus react publicly and in a timely manner
> +    to any inquiries. Test proposed fixes. Do proactive testing when a new rc1
> +    gets released. Sent friendly reminders if things stall. And try to help

                      Send

> +    yourself, if you don't get any help or if it is unsatisfying.*
> +
> +If your report was good and you are really lucky then one of the developers
> +might immediately spot what's causing the issue; then he might write a patch to
> +fix it, test it, and sends it straight for integration in mainline while

                        send

> +tagging it for later backport to stable and longterm kernels that need it. Then
> +all you need to do is reply with a 'Thank you very much' and switch to a
> +version with the fix once it gets released.
> +
> +But this ideal scenario rarely happens, that's why the job is only starting once

                                  happens. That's

> +you got the report out. What you'll have to do depends on the issue, but often
> +it will be the things listed below. But before digging into the details a few

                                                                   details, here are a few

> +important things you need to keep in mind for this part of the process.
> +
> +General advice for further interactions
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +*Always reply in public*: When the issue was filed in a bug tracker always
> +reply there and do not contact any of the developer privately about it. For

                                             developers

> +mailed reports always use the 'Reply-all' function when replying to any mails
> +you receive. That includes mails with any additional data you might want to add
> +to your report: go to your mail applications 'Sent' folder and use 'reply-all'
> +on your mail with the report. This approach will make sure the public mailing
> +list(s) and everyone else that gets involved over time always stays in the
> +loop; it also keeps the mail thread intact, which among others is really
> +important for mailing list to group all related mails together.
> +
> +There are just two situations where a comment in a bug tracker or a 'Reply-all'
> +is unsuitable:
> +
> + * Someone tells you to send something privately.
> +
> + * You were told to sent something, but noticed it contains sensitive

                       send

> +   information that really needs to be kept private. In that case it's okay to
> +   sent it in private to the developer that asked for it. But point in the

      send                                                   But note in the

> +   ticket or a mail that you did that, so everyone else knows the request was
> +   honored.
> +
> +*Do research before asking for clarifications or help*: In this part of the
> +process someone might tell you to do something that requires a skill you might
> +not have mastered yet. For example, you might get ask to use some test tools

                                                 be asked

> +you never have heard of yet; or you might get asked to apply a patch to the

                                             be

> +Linux kernel sources to test if it helps. In some cases it will be fine sending
> +a reply asking for instructions how to do that. But before going that route try
> +to find the answer own your own by searching the internet; alternatively
> +consider asking a friend or in some chatroom/forum you normally hang out for
> +advice.
> +
> +*Be patient*: If you are really lucky you might get a reply to your report
> +within a few hours. But most of the time it will take longer, as maintainers
> +are scattered around the globe and thus might be in a different time zone – one
> +where they already enjoy their evening away from keyboard.
> +
> +In general, kernel developers will take one to five business days to respond to
> +reports. Sometimes it will take longer, as they might be busy with other work,
> +visiting developer conferences, or simply enjoying a long summer holiday.
> +
> +The 'issues of high priority' (see above for an explanation) are an exception
> +here: maintainer should address them as soon as possible, that's why you should

         maintainers                               possible; that's

> +wait a week at maximum (or just two days if it's something urgent) before
> +sending a friendly reminder. If the maintainer is not responding in a timely
> +manner or not handing it appropriately, mention that you are considering to
> +escalate the issue to a higher authority and do so if there is in the end

                                            and do so if there seems to be
no way around this.

although such a "threat" probably won't do much good.

> +there seems to be no way around this. In case of Wi-Fi driver code you for
> +example would escalate it to the wireless maintainers; if there are no higher
> +level maintainers or all else fails it might be one of those situations where
> +it's okay to get Linus Torvalds involved directly.
> +
> +*Proactive testing*: Every time the first pre-release (the 'rc1') of a new
> +mainline kernel version gets released, go and check if the issue is fixed there
> +or if anything of importance changed. Mention the outcome in the ticket or in a
> +reply to the report (make sure it has all those in the CC that up to that point
> +participated in the discussion). This will show your commitment and that you
> +are willing to help. It also tells developers if the issue persists and makes
> +sure they do not forget about it. A few other occasional retests (for example
> +with rc3, rc6 and the final) are also a good idea, but only report your results
> +if something relevant changed or if you are writing something anyway.
> +
> +With all these general things off the table let's get into the details how to

                                                                  details of how to

> +help to get issues resolved once they were reported.
> +
> +Inquires and testing request
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Here are your duties in case you got replies to your report:
> +
> + *Check who you deal with*: Most of the time it will be the maintainer or a
> + developer of the particular code area that will respond to your report. But as
> + issues are normally reported in public it could be anyone that's replying —
> + including people that want to help, but in the end might guide you totally off
> + track with their questions or requests. That rarely happens, but it's one of
> + many reasons why it's wise to quickly run an internet search to see who you're
> + interacting with. You also get aware if your report was heard by the right
> + people, as a reminder to the maintainer (see below) might be in order later if
> + discussion fades out and does not lead to a fix.
> +
> + *Inquires for data*: Often you will be asked to test something or provide

     Inquiries

> + additional details. Try to provide the information requested soon, as you have
> + the attention of someone that might help and risk losing it the longer you
> + wait; that outcome is even likely if you do not provide the information within
> + a few business days.
> +
> + *Requests for testing*: When you get asked to test a diagnostic patch or a

                                     are

> + possible fix try to test it in timely manner, too. Do it properly and make

             fix,

> + sure to not rush it: mixing things up can happen easily and lead to a lot
> + of confusion for everyone involved. A common mistake for example is thinking a
> + kernel patch that might fix the issue was applied, but in fact wasn't – even
> + experienced testers make such mistakes occasionally and only notice when the
> + kernel built from those sources behaves just as before.
> +
> +What to do when nothing of substance happens
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Some report will not get any reaction from the responsible Linux kernel

        reports

> +developers; or a discussion around the issue evolved, but it faded out and
> +nothing of substance came out of it.
> +
> +In these cases wait two (better: three) weeks before sending a friendly
> +reminder: maybe the maintainer was just away from keyboard for a while when
> +your report arrived or had something more important to take care of. When
> +writing the reminder, kindly ask if anything else from your side is needed to
> +get the ball running somehow. If the report got out by mail do that in the first
> +lines of a mail that is a reply to your initial mail (see above) which includes
> +a full quote of the original report below: that's on of those few situations
> +where such a 'TOFU' (Text Over, Fullquote Under) is the right approach, as then
> +all the recipients will have the details at hand immediately in the proper
> +order.
> +
> +After the reminder wait three more weeks for replies. If you still don't get a
> +proper reaction, you first should reconsider your approach. Did you maybe try
> +to reach out to the wrong people? Was the report maybe offensive or so
> +confusing that people decided to completely stay away from it? The best way to
> +rule out such factors: show the report to one or two people familiar with FLOSS
> +issue reporting and ask for their option. Also ask them for their advice how to

                                     opinion.

> +move forward. That might mean: prepare a better report and make those people
> +review it before you sent it out. Such an approach it totally fine, just

                        send                          is         fine; just

> +mentions that this is the second and improved report on the issue and include a

   mention

> +link to the first report.
> +
> +If the report was proper you can send a second reminder; in it ask for advice
> +why the report did not get any replies. A good moment for this second reminder
> +mail is shortly after the first pre-release (the 'rc1') of a new Linux kernel
> +version got published, as you should retest at that point anyway (see above).
> +
> +If the second reminder again results in no reaction within a week, try to
> +contact a higher-level maintainer asking for advice: even busy maintainers by
> +then should at least have sent some kind of acknowledgment.
> +
> +Remember to prepare yourself for a disappointment: maintainers ideally should
> +react somehow to every issue report, but they are only obliged to fix those
> +'issues of high priority' outlined earlier. So don't be too devastating if you
> +get a  reply along the lines of 'thanks for the report, I have more important
> +issues to deal with currently and won't have time to look into this for the
> +foreseeable future'.
> +
> +It's also possible that after some discussion in the bug tracker or one a list

                                                                       on a list

> +nothing happens anymore and reminders don't help to motivate anyone to work out
> +a fix. Such situations can be devastating, but is within the cards when if

                                                                           it

> +comes to Linux kernel development. This and sore other reasons for not getting

                                               several

> +help are explained in 'Why some issues won't get any reaction or remain unfixed
> +after being reported' near the end of this document.
> +
> +Don't get devastated if you don't get any help or if the issue in the end does
> +not get solved: as this the Linux kernel is FLOSS and thus you can still help
> +yourself. Find others that are affected and try to team up with them to get the
> +issue resolved. You for example can prepare a fresh report together that
> +mentions how many you are and why this is something that in your option should
> +get fixed. Maybe together you can also narrow down the root cause or the change
> +that introduced a regression, which often makes developing a fix easier. And
> +with a bit of luck there might be someone in the team that knows a bit about
> +programming and might be able to write a fix.
> +
> +
>  .. ############################################################################
>  .. 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.


-- 
~Randy

Re: [RFC PATCH v1 22/26] docs: reporting-bugs: explain what users should do once the report got out

[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 09.10.20 um 19:37 schrieb Randy Dunlap:
> On 10/1/20 1:50 AM, Thorsten Leemhuis wrote:

>> +wait a week at maximum (or just two days if it's something urgent) before
>> +sending a friendly reminder. If the maintainer is not responding in a timely
>> +manner or not handing it appropriately, mention that you are considering to
>> +escalate the issue to a higher authority and do so if there is in the end
> 
>                                              and do so if there seems to be
> no way around this.
> 
> although such a "threat" probably won't do much good.

Hmmm, yeah, I guess did not find the right tone here. But I think this 
situation needs to be mentioned in the text. And FWIW, something about 
it is even in the old text:

"""
If you suspect a maintainer is not responding to these types of bugs in 
a timely manner (especially during a merge window), escalate the bug to 
LKML and Linus Torvalds.
""""

So how about this:
```
The 'issues of high priority' (see above for an explanation) are an 
exception here: maintainers should address them as soon as possible; 
that's why you should wait a week at maximum (or just two days if it's 
something urgent) before sending a friendly reminder.

Sometimes the maintainer might not be responding in a timely manner; 
other times there might be disagreements, for example if an issue 
qualifies as regression or not. In such cases raise your concerns on the 
mailing list and ask others for public or private replies how to move 
on. If that fails, it might be appropriate to escalate the issue to a 
higher authority. In case of a WiFi driver that would be the wireless 
maintainers; if there are no higher level maintainers or all else fails, 
it might be one of those rare situations where it's okay to get Linus 
Torvalds involved.
```


Still not totally happy with it, but I better at least. Or what do other 
think about it?

Ciao, Thorsten

Re: [RFC PATCH v1 22/26] docs: reporting-bugs: explain what users should do once the report got out

[Randy Dunlap]

On 10/11/20 6:29 AM, Thorsten Leemhuis wrote:
> 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 09.10.20 um 19:37 schrieb Randy Dunlap:
>> On 10/1/20 1:50 AM, Thorsten Leemhuis wrote:
> 
>>> +wait a week at maximum (or just two days if it's something urgent) before
>>> +sending a friendly reminder. If the maintainer is not responding in a timely
>>> +manner or not handing it appropriately, mention that you are considering to
>>> +escalate the issue to a higher authority and do so if there is in the end
>>
>>                                              and do so if there seems to be
>> no way around this.
>>
>> although such a "threat" probably won't do much good.
> 
> Hmmm, yeah, I guess did not find the right tone here. But I think this situation needs to be mentioned in the text. And FWIW, something about it is even in the old text:
> 
> """
> If you suspect a maintainer is not responding to these types of bugs in a timely manner (especially during a merge window), escalate the bug to LKML and Linus Torvalds.
> """"
> 
> So how about this:
> ```
> The 'issues of high priority' (see above for an explanation) are an exception here: maintainers should address them as soon as possible; that's why you should wait a week at maximum (or just two days if it's something urgent) before sending a friendly reminder.
> 
> Sometimes the maintainer might not be responding in a timely manner; other times there might be disagreements, for example if an issue qualifies as regression or not. In such cases raise your concerns on the mailing list and ask others for public or private replies how to move on. If that fails, it might be appropriate to escalate the issue to a higher authority. In case of a WiFi driver that would be the wireless maintainers; if there are no higher level maintainers or all else fails, it might be one of those rare situations where it's okay to get Linus Torvalds involved.
> ```
> 
> 
> Still not totally happy with it, but I better at least. Or what do other think about it?

Thanks, it's better.

-- 
~Randy

[RFC PATCH v1 23/26] docs: reporting-bugs: details for issues specific to stable and longterm

[Thorsten Leemhuis]

Describe what users have to do if they can't reproduce a problem with
mainline they want to see fixed in stable and longterm kernels. This is
separated from the main flow, as integrating it there would make it
harder to follow.

Note users will only enter this section in two cases: (1) the issue was
fixed in mainline (on purpose or accidentally) (2) it's a regression
that never was present in mainline (for example due to a broken
backport).

Help users to differentiate between the two, as they ideally are handled
differently.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 191 +++++++++++++++++--
 1 file changed, 179 insertions(+), 12 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index b8bc6c4e2340..340fa44b352c 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -1223,24 +1223,191 @@ with a bit of luck there might be someone in the team that knows a bit about
 programming and might be able to write a fix.
 
 
+Details about reporting issues only occurring in older kernel version lines
+---------------------------------------------------------------------------
+
+Find below details about the steps in the subsection for reporting issues that
+only happen in stable and longterm kernels.
+
+
+Some fixes are too complex
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    *Prepare yourself for the possibility that going through the next few steps
+    might not get the issue solved in older releases: the fix might be too big
+    or risky to get backported there.*
+
+Even small and seemingly obvious code-changes sometimes introduce new and
+totally unexpected problems. The maintainers of the stable and longterm kernels
+are very aware of that and thus only apply changes to these kernels that are
+:ref:`within rules outlined in Documentation/process/stable-kernel-rules.rst
+<stable_kernel_rules>`.
+
+Complex or risky changes for example do not qualify and thus only get applied to
+mainline; sometimes fixes are easy to get backported to the newest stable and
+longterm kernels, but too risky to integrate into older ones. So be aware the
+fix you are hoping for might be one of those and that you have no other choice
+then to live with the issue or switch to a newer version, unless you want to
+patch the fix into your own kernels yourselfs.
+
+
+Make sure the particular version line is still supported
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    *Check if the kernel developers still maintain the Linux kernel version line
+    you care about: go to the front-page of kernel.org and make sure it mentions
+    the latest release of the particular version line without an '[EOL]' tag.*
+
+Most kernel version lines only get supported for about three months, as
+maintaining them longer is quite a lot of work. Hence, only one per year is
+chosen and gets supported for at least two years (often six). That's why you
+need to check if the kernel developer still support the version line you care
+for.
+
+Note: if kernel.org lists two 'stable' version lines, you likely want to focus
+on the newer of the two, as support for the older is likely to be abandoned
+soon and thus "end-of-life" (EOL). Version lines that reached that point still
+get mentioned on the kernel.org-frontpage for a week or two, but then they are
+unsuitable for testing and reporting.
+
+
+Search stable mailing list
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    *Check the archives of the Linux stable mailing list for existing reports.*
+
+Maybe the issue you face is already known and was fixed or is about to. Hence,
+`search the archives of the Linux stable mailing list
+<https://lore.kernel.org/stable/>`_ for reports about an issue like yours. If
+you find any matches, consider joining the discussion, unless the fix is already
+finished and scheduled to get applied soon.
+
+
+Reproduce issue with the newest release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+   *Install the latest release from the particular version line as a vanilla
+   kernel. Ensure this kernel is not tainted and still shows the problem, as the
+   issue might have already been fixed there.*
+
+Before investing any more time in this you want to check if the issue was
+already fixed in the latest release of version line you're interested in. This
+kernel needs to be vanilla and shouldn't be tainted before the issue happens, as
+detailed outlined already above in the process of testing mainline.
+
+
+Check code history and search for existing discussions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    *Search the Linux kernel version control system for the change that fixed
+    the issue in mainline, as its commit message might tell you if the fix is
+    scheduled for backporting already. If you don't find anything that way,
+    search the appropriate mailing lists for posts that discuss such an issue or
+    peer-review possible fixes. That might lead you to the commit with the fix
+    or tell you if it's unsuitable for backporting. If backporting was not
+    considered at all, join the newest discussion, asking if its in the cards.*
+
+In a lot of cases the issue you deal with, will have happened with mainline,
+but got fixed there. The commit that fixed it would need to get backported as
+well to get the issue solved. That why you want to search for it or any
+discussions abound it.
+
+ * First try to find the fix on the Git repository that holds the Linux kernel
+   sources. You can do this with the web interfaces `on kernel.org
+   <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_
+   or its mirror `on GitHub <https://github.com/torvalds/linux>`_; if you have a
+   local clone you alternatively can search on the command line with
+   ``git log --grep=<pattern>``.
+
+   If you find the fix, look if the commit message near the end contains a
+   'stable tag' that looks like this:
+
+          Cc: <stable@vger.kernel.org> # 5.4+
+
+   If that's case the developer marked the fix safe for backporting to version
+   line 5.4 and later. Most of the time it's getting applied there within two
+   weeks, but sometimes it takes a bit longer.
+
+ * If the commit doesn't tell you anything or if you can't find the fix, look
+   again for discussions about the issue. Search the net with your favorite
+   internet    search engine as well as the archives for the `Linux kernel
+   developers mailing list <https://lore.kernel.org/lkml/>`_. Also read the
+   section `Locate kernel area that causes the issue` above and follow the
+   instructions to find  the subsystem in question: its bug tracker or mailing
+   list archive might have the answer you are looking for.
+
+   * If you see a proposed fix, search for it in the version control system as
+     outlined above, as the commit might tell you if a backport can be expected.
+
+   * Check the discussions for any indicators the fix might be too risky to get
+     backported to the version line you care about. If that's the case you have
+     to live with the issue or switch to the kernel version line where the fix
+     got applied.
+
+   * If the fix doesn't contain a stable tag and backporting was not discussed,
+     join the discussion: mention the version where you face the issue and that
+     you would like to see it fixed, if suitable.
+
+
+Check if it's a regression specific to stable or longterm kernels
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    *Check if you're dealing with a regression that was never present in
+    mainline by installing the first release of the version line you care about.
+    If the issue doesn't show up with it, you basically need to report the issue
+    with this version like you would report a problem with mainline (see above).
+    This ideally includes a bisection followed by a search for existing reports
+    on the net; with the help of the subject and the two relevant commit-ids. If
+    that doesn't turn up anything, write the report; CC or forward the report to
+    the stable maintainers, the stable mailing list, and those that authored the
+    change. Include the shortened commit-id if you found the change that causes
+    it.*
+
+Sometimes you won't find anything in the previous step: the issue you face might
+have never occurred in mainline, as it its caused by some change that is
+incomplete or not correctly applied. To check this, install the first release
+from version line you care about, e.g. if you care about 5.4.x, install 5.4.
+
+If the issue doesn't show itself there, it's a regression specific to the
+particular version line. In that case you need to report it like an issue
+happening in mainline, like the last few steps in the main section above
+outline.
+
+One of them suggests doing a bisection, which you are strongly advised to do in
+this case. After finding the culprit, search the net for existing reports again:
+not only search for the exact subject and the commit-id (proper and shortened to
+twelve characters) of the change, but also for the commit-id (proper and
+shortened) mentioned as 'Upstream commit' in the commit message.
+
+Write the report, just keep a few specialties in mind: CC or forward the report
+to the stable maintainers, the stable mailing list, which the `MAINTAINERS file
+<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
+mentions in the section "STABLE BRANCH". If you performed a successful
+bisection, CC the author of the change and include its subject and the shortened
+commit-id.
+
+Ask for advice
+~~~~~~~~~~~~~~
+
+    *One of the former steps should lead to a solution. If that doesn't work
+    out, ask the maintainers for the subsystem that seems to be causing the
+    issue for advice; CC the mailing list for the particular subsystem as well
+    as the stable mailing list.*
+
+If the previous three steps didn't get you closer to a solution there is only
+one option left: ask for advice. Do that in a mail you sent to the maintainers
+for the subsystem where the issue seems to have its roots; CC the mailing list
+for the subsystem as well as the stable mailing list the `MAINTAINERS file
+<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
+mention in the section "STABLE BRANCH".
+
+
 .. ############################################################################
 .. 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.
 .. Both sections are incomplete as of now and thus sometimes inconsistent.
 .. ###########################################################################
 
-Background
-==========
-
-The upstream Linux kernel maintainers only fix bugs for specific kernel
-versions.  Those versions include the current "release candidate" (or -rc)
-kernel, any "stable" kernel versions, and any "long term" kernels.
-
-Please see https://www.kernel.org/ for a list of supported kernels.  Any
-kernel marked with [EOL] is "end of life" and will not have any fixes
-backported to it.
-
-
 How to report Linux kernel bugs
 ===============================
 
-- 
2.26.2

Re: [RFC PATCH v1 23/26] docs: reporting-bugs: details for issues specific to stable and longterm

[Randy Dunlap]

On 10/1/20 1:50 AM, Thorsten Leemhuis wrote:
> Describe what users have to do if they can't reproduce a problem with
> mainline they want to see fixed in stable and longterm kernels. This is
> separated from the main flow, as integrating it there would make it
> harder to follow.
> 
> Note users will only enter this section in two cases: (1) the issue was
> fixed in mainline (on purpose or accidentally) (2) it's a regression

                                   accidentally); (2)

> that never was present in mainline (for example due to a broken
> backport).
> 
> Help users to differentiate between the two, as they ideally are handled
> differently.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 191 +++++++++++++++++--
>  1 file changed, 179 insertions(+), 12 deletions(-)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index b8bc6c4e2340..340fa44b352c 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -1223,24 +1223,191 @@ with a bit of luck there might be someone in the team that knows a bit about
>  programming and might be able to write a fix.
>  
>  
> +Details about reporting issues only occurring in older kernel version lines
> +---------------------------------------------------------------------------
> +
> +Find below details about the steps in the subsection for reporting issues that
> +only happen in stable and longterm kernels.
> +
> +
> +Some fixes are too complex
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +    *Prepare yourself for the possibility that going through the next few steps
> +    might not get the issue solved in older releases: the fix might be too big
> +    or risky to get backported there.*
> +
> +Even small and seemingly obvious code-changes sometimes introduce new and
> +totally unexpected problems. The maintainers of the stable and longterm kernels
> +are very aware of that and thus only apply changes to these kernels that are
> +:ref:`within rules outlined in Documentation/process/stable-kernel-rules.rst
> +<stable_kernel_rules>`.
> +
> +Complex or risky changes for example do not qualify and thus only get applied to
> +mainline; sometimes fixes are easy to get backported to the newest stable and
> +longterm kernels, but too risky to integrate into older ones. So be aware the
> +fix you are hoping for might be one of those and that you have no other choice
> +then to live with the issue or switch to a newer version, unless you want to
> +patch the fix into your own kernels yourselfs.

                                       yourself.

> +
> +
> +Make sure the particular version line is still supported
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +    *Check if the kernel developers still maintain the Linux kernel version line
> +    you care about: go to the front-page of kernel.org and make sure it mentions

                                 front page

> +    the latest release of the particular version line without an '[EOL]' tag.*
> +
> +Most kernel version lines only get supported for about three months, as
> +maintaining them longer is quite a lot of work. Hence, only one per year is
> +chosen and gets supported for at least two years (often six). That's why you
> +need to check if the kernel developer still support the version line you care

                               devlopers

> +for.
> +
> +Note: if kernel.org lists two 'stable' version lines, you likely want to focus
> +on the newer of the two, as support for the older is likely to be abandoned
> +soon and thus "end-of-life" (EOL). Version lines that reached that point still
> +get mentioned on the kernel.org-frontpage for a week or two, but then they are

                        kernel.org front page

> +unsuitable for testing and reporting.
> +
> +
> +Search stable mailing list
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +    *Check the archives of the Linux stable mailing list for existing reports.*
> +
> +Maybe the issue you face is already known and was fixed or is about to. Hence,
> +`search the archives of the Linux stable mailing list
> +<https://lore.kernel.org/stable/>`_ for reports about an issue like yours. If
> +you find any matches, consider joining the discussion, unless the fix is already
> +finished and scheduled to get applied soon.
> +
> +
> +Reproduce issue with the newest release
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +   *Install the latest release from the particular version line as a vanilla
> +   kernel. Ensure this kernel is not tainted and still shows the problem, as the
> +   issue might have already been fixed there.*
> +
> +Before investing any more time in this you want to check if the issue was
> +already fixed in the latest release of version line you're interested in. This
> +kernel needs to be vanilla and shouldn't be tainted before the issue happens, as
> +detailed outlined already above in the process of testing mainline.
> +
> +
> +Check code history and search for existing discussions
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +    *Search the Linux kernel version control system for the change that fixed
> +    the issue in mainline, as its commit message might tell you if the fix is
> +    scheduled for backporting already. If you don't find anything that way,
> +    search the appropriate mailing lists for posts that discuss such an issue or
> +    peer-review possible fixes. That might lead you to the commit with the fix
> +    or tell you if it's unsuitable for backporting. If backporting was not
> +    considered at all, join the newest discussion, asking if its in the cards.*

                                                                it's

> +
> +In a lot of cases the issue you deal with, will have happened with mainline,

                                        with will

> +but got fixed there. The commit that fixed it would need to get backported as
> +well to get the issue solved. That why you want to search for it or any
> +discussions abound it.
> +
> + * First try to find the fix on the Git repository that holds the Linux kernel

I would say                     in
but maybe it doesn't matter.

> +   sources. You can do this with the web interfaces `on kernel.org
> +   <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_
> +   or its mirror `on GitHub <https://github.com/torvalds/linux>`_; if you have a
> +   local clone you alternatively can search on the command line with
> +   ``git log --grep=<pattern>``.
> +
> +   If you find the fix, look if the commit message near the end contains a
> +   'stable tag' that looks like this:
> +
> +          Cc: <stable@vger.kernel.org> # 5.4+
> +
> +   If that's case the developer marked the fix safe for backporting to version
> +   line 5.4 and later. Most of the time it's getting applied there within two
> +   weeks, but sometimes it takes a bit longer.
> +
> + * If the commit doesn't tell you anything or if you can't find the fix, look
> +   again for discussions about the issue. Search the net with your favorite
> +   internet    search engine as well as the archives for the `Linux kernel

              ^^^ too many spaces.

> +   developers mailing list <https://lore.kernel.org/lkml/>`_. Also read the
> +   section `Locate kernel area that causes the issue` above and follow the
> +   instructions to find  the subsystem in question: its bug tracker or mailing

                          ^^ drop one space.

> +   list archive might have the answer you are looking for.
> +
> +   * If you see a proposed fix, search for it in the version control system as
> +     outlined above, as the commit might tell you if a backport can be expected.
> +
> +   * Check the discussions for any indicators the fix might be too risky to get
> +     backported to the version line you care about. If that's the case you have
> +     to live with the issue or switch to the kernel version line where the fix
> +     got applied.
> +
> +   * If the fix doesn't contain a stable tag and backporting was not discussed,
> +     join the discussion: mention the version where you face the issue and that
> +     you would like to see it fixed, if suitable.
> +
> +
> +Check if it's a regression specific to stable or longterm kernels
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +    *Check if you're dealing with a regression that was never present in
> +    mainline by installing the first release of the version line you care about.
> +    If the issue doesn't show up with it, you basically need to report the issue
> +    with this version like you would report a problem with mainline (see above).
> +    This ideally includes a bisection followed by a search for existing reports
> +    on the net; with the help of the subject and the two relevant commit-ids. If
> +    that doesn't turn up anything, write the report; CC or forward the report to
> +    the stable maintainers, the stable mailing list, and those that authored the
> +    change. Include the shortened commit-id if you found the change that causes
> +    it.*
> +
> +Sometimes you won't find anything in the previous step: the issue you face might
> +have never occurred in mainline, as it its caused by some change that is

                                    as it is caused

> +incomplete or not correctly applied. To check this, install the first release
> +from version line you care about, e.g. if you care about 5.4.x, install 5.4.
> +
> +If the issue doesn't show itself there, it's a regression specific to the
> +particular version line. In that case you need to report it like an issue
> +happening in mainline, like the last few steps in the main section above

                                                  in the main section in the above

> +outline.
> +
> +One of them suggests doing a bisection, which you are strongly advised to do in
> +this case. After finding the culprit, search the net for existing reports again:
> +not only search for the exact subject and the commit-id (proper and shortened to
> +twelve characters) of the change, but also for the commit-id (proper and
> +shortened) mentioned as 'Upstream commit' in the commit message.
> +
> +Write the report, just keep a few specialties in mind: CC or forward the report

             report; just

> +to the stable maintainers, the stable mailing list, which the `MAINTAINERS file
> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
> +mentions in the section "STABLE BRANCH". If you performed a successful
> +bisection, CC the author of the change and include its subject and the shortened
> +commit-id.
> +
> +Ask for advice
> +~~~~~~~~~~~~~~
> +
> +    *One of the former steps should lead to a solution. If that doesn't work
> +    out, ask the maintainers for the subsystem that seems to be causing the
> +    issue for advice; CC the mailing list for the particular subsystem as well
> +    as the stable mailing list.*
> +
> +If the previous three steps didn't get you closer to a solution there is only
> +one option left: ask for advice. Do that in a mail you sent to the maintainers
> +for the subsystem where the issue seems to have its roots; CC the mailing list
> +for the subsystem as well as the stable mailing list the `MAINTAINERS file
> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
> +mention in the section "STABLE BRANCH".
> +
> +


-- 
~Randy

Re: [RFC PATCH v1 23/26] docs: reporting-bugs: details for issues specific to stable and longterm

[Thorsten Leemhuis]

Am 09.10.20 um 20:42 schrieb Randy Dunlap:
> On 10/1/20 1:50 AM, Thorsten Leemhuis wrote:

Many thx for you comments, all suggestions implemented.


Ciao, Thorsten

[RFC PATCH v1 24/26] docs: reporting-bugs: explain why users might get neither reply nor fix

[Thorsten Leemhuis]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=yes, Size: 4608 bytes --]

Not even getting a reply after one invested quite a bit of time with
preparing and writing a report can be quite devastating. But when it
comes to Linux, this can easily happen for good or bad reasons. Hence,
use this opportunity to explain why this might happen, hopefully some
people then will be less disappointed if it happens.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 56 ++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 340fa44b352c..8f60af27635b 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -1402,6 +1402,62 @@ for the subsystem as well as the stable mailing list the `MAINTAINERS file
 mention in the section "STABLE BRANCH".
 
 
+Why some issues won't get any reaction or remain unfixed after being reported
+=============================================================================
+
+When reporting a problem to the Linux developers, be aware only 'issues of high
+priority' (regression, security issue, severe problems) are definitely going to
+get resolved. The maintainers or if all else fails Linus Torvalds himself will
+make sure of that. They and the other kernel developers will fix a lot of other
+issues as well. But be aware that sometimes they can't or won't help; and
+sometimes there isn't even anyone to send a report to.
+
+This is best explained with kernel developers that contribute to the Linux
+kernel in their spare time. Quite a few of the drivers in the kernel were
+written by such programmers, often because they simply wanted to make their
+hardware usable on their favorite operating system.
+
+These programmers most of the time will happily fix problems other people
+report. But nobody can force them to do, as they are contributing voluntarily.
+
+Then there are situations where such developers really want to fix an issue,
+but can't: they lack hardware programming documentation to do so. This often
+happens when the publicly available docs are superficial or the driver was
+written with the help of reverse engineering.
+
+Sooner or later spare time developers will also stop caring for the driver.
+Maybe their test hardware broke, got replaced by something more fancy, or is so
+old that it's something you don't find much outside of computer museums
+anymore. Or the developer stops caring for their code and Linux at all, as
+something different in their life became way more important. Sometimes nobody
+is willing to take over the job as maintainer – and nobody can be forced to, as
+contributing to the Linux kernel is done on a voluntary basis. Abandoned
+drivers nevertheless remain in the kernel: they are still useful for people and
+removing would be a regression.
+
+The situation is not that different with developers that are paid for their
+work on the Linux kernel. Those contribute most changes these days. But their
+employers sooner or later also stop caring for some code and make its programmer
+focus on other thing. Hardware vendors for example earn their money mainly by
+selling new hardware; quite a few of them hence are not investing much time and
+energy in maintaining a Linux kernel driver for something they sold years ago.
+Enterprise Linux distributors often care for a longer time period, but in new
+version often leave support for old and rare hardware aside to limit the scope.
+Often spare time contributors take over once a company leaves some orphan some
+code, but as mentioned above: sooner or later will leave the code behind, too.
+
+Priorities are another reason why some issues are not fixed, as maintainers
+quite often are forced to set those, as time to work on Linux is limited. That's
+true for spare time or the time employers grant their developers to spend on
+maintenance work on the upstream kernel. Sometimes maintainers also get
+overwhelmed with reports, even if a driver is working nearly perfectly. To not
+get completely stuck, the programmer thus might have no other choice then to
+prioritize issue reports and reject some of them.
+
+But don't worry too much about all of this, a lot of drivers have active
+maintainers who are quite interested in fixing as many issues as possible.
+
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

Re: [RFC PATCH v1 24/26] docs: reporting-bugs: explain why users might get neither reply nor fix

[Randy Dunlap]

On 10/1/20 1:50 AM, Thorsten Leemhuis wrote:
> Not even getting a reply after one invested quite a bit of time with
> preparing and writing a report can be quite devastating. But when it
> comes to Linux, this can easily happen for good or bad reasons. Hence,
> use this opportunity to explain why this might happen, hopefully some
> people then will be less disappointed if it happens.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 56 ++++++++++++++++++++
>  1 file changed, 56 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 340fa44b352c..8f60af27635b 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -1402,6 +1402,62 @@ for the subsystem as well as the stable mailing list the `MAINTAINERS file
>  mention in the section "STABLE BRANCH".
>  
>  
> +Why some issues won't get any reaction or remain unfixed after being reported
> +=============================================================================
> +
> +When reporting a problem to the Linux developers, be aware only 'issues of high
> +priority' (regression, security issue, severe problems) are definitely going to
> +get resolved. The maintainers or if all else fails Linus Torvalds himself will
> +make sure of that. They and the other kernel developers will fix a lot of other
> +issues as well. But be aware that sometimes they can't or won't help; and
> +sometimes there isn't even anyone to send a report to.
> +
> +This is best explained with kernel developers that contribute to the Linux
> +kernel in their spare time. Quite a few of the drivers in the kernel were
> +written by such programmers, often because they simply wanted to make their
> +hardware usable on their favorite operating system.
> +
> +These programmers most of the time will happily fix problems other people
> +report. But nobody can force them to do, as they are contributing voluntarily.
> +
> +Then there are situations where such developers really want to fix an issue,
> +but can't: they lack hardware programming documentation to do so. This often
> +happens when the publicly available docs are superficial or the driver was
> +written with the help of reverse engineering.
> +
> +Sooner or later spare time developers will also stop caring for the driver.
> +Maybe their test hardware broke, got replaced by something more fancy, or is so
> +old that it's something you don't find much outside of computer museums
> +anymore. Or the developer stops caring for their code and Linux at all, as
> +something different in their life became way more important. Sometimes nobody
> +is willing to take over the job as maintainer – and nobody can be forced to, as
> +contributing to the Linux kernel is done on a voluntary basis. Abandoned
> +drivers nevertheless remain in the kernel: they are still useful for people and
> +removing would be a regression.
> +
> +The situation is not that different with developers that are paid for their
> +work on the Linux kernel. Those contribute most changes these days. But their
> +employers sooner or later also stop caring for some code and make its programmer
> +focus on other thing. Hardware vendors for example earn their money mainly by

         on other things.

> +selling new hardware; quite a few of them hence are not investing much time and
> +energy in maintaining a Linux kernel driver for something they sold years ago.
> +Enterprise Linux distributors often care for a longer time period, but in new
> +version often leave support for old and rare hardware aside to limit the scope.
> +Often spare time contributors take over once a company leaves some orphan some

                                                                  drop last: some

> +code, but as mentioned above: sooner or later will leave the code behind, too.

                                           later they will leave the code behind, too.

> +
> +Priorities are another reason why some issues are not fixed, as maintainers
> +quite often are forced to set those, as time to work on Linux is limited. That's
> +true for spare time or the time employers grant their developers to spend on
> +maintenance work on the upstream kernel. Sometimes maintainers also get
> +overwhelmed with reports, even if a driver is working nearly perfectly. To not
> +get completely stuck, the programmer thus might have no other choice then to

                                                                        than to

> +prioritize issue reports and reject some of them.
> +
> +But don't worry too much about all of this, a lot of drivers have active
> +maintainers who are quite interested in fixing as many issues as possible.
> +
> +
>  .. ############################################################################
>  .. 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.
> 


-- 
~Randy

Re: [RFC PATCH v1 24/26] docs: reporting-bugs: explain why users might get neither reply nor fix

[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:50 AM, Thorsten Leemhuis wrote:

>> +selling new hardware; quite a few of them hence are not investing much time and
>> +energy in maintaining a Linux kernel driver for something they sold years ago.
>> +Enterprise Linux distributors often care for a longer time period, but in new
>> +version often leave support for old and rare hardware aside to limit the scope.
>> +Often spare time contributors take over once a company leaves some orphan some
>                                                                   drop last: some
>> +code, 

/me looks closer

Changed to (that's what it was supposed to be):

Often spare time contributors take over once a company orphans some
code, […]

Ciao, Thorsten

[RFC PATCH v1 25/26] docs: reporting-bugs: explain things could be easier

[Thorsten Leemhuis]

A few closing words to explain why things are like this until someone
steps up to make things easier for people.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 8f60af27635b..42f59419263a 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -1458,6 +1458,15 @@ But don't worry too much about all of this, a lot of drivers have active
 maintainers who are quite interested in fixing as many issues as possible.
 
 
+Closing words
+=============
+
+Compared with other Free/Libre & Open Source Software it's hard to reporting
+issues to the Linux kernel developers: the length and complexity of this
+document and the implications between the lines illustrate that. But that's how
+it is for now. The main author of this text hopes documenting the state of the
+art will lay some groundwork to improve the situation over time.
+
 .. ############################################################################
 .. 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.
-- 
2.26.2

Re: [RFC PATCH v1 25/26] docs: reporting-bugs: explain things could be easier

[Randy Dunlap]

On 10/1/20 1:50 AM, Thorsten Leemhuis wrote:
> A few closing words to explain why things are like this until someone
> steps up to make things easier for people.
> 
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/admin-guide/reporting-bugs.rst | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
> index 8f60af27635b..42f59419263a 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -1458,6 +1458,15 @@ But don't worry too much about all of this, a lot of drivers have active
>  maintainers who are quite interested in fixing as many issues as possible.
>  
>  
> +Closing words
> +=============
> +
> +Compared with other Free/Libre & Open Source Software it's hard to reporting

                                                                   to report

> +issues to the Linux kernel developers: the length and complexity of this
> +document and the implications between the lines illustrate that. But that's how
> +it is for now. The main author of this text hopes documenting the state of the
> +art will lay some groundwork to improve the situation over time.
> +
>  .. ############################################################################
>  .. 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.
> 


-- 
~Randy

Re: [RFC PATCH v1 25/26] docs: reporting-bugs: explain things could be easier

[Thorsten Leemhuis]

Am 04.10.20 um 06:03 schrieb Randy Dunlap:
> On 10/1/20 1:50 AM, Thorsten Leemhuis wrote:
>> +Compared with other Free/Libre & Open Source Software it's hard to reporting
>                                                                    to report

Fixed, thx! Ciao, Thorsten

[RFC PATCH v1 26/26] docs: reporting-bugs: add SPDX tag and license hint, remove markers

[Thorsten Leemhuis]

Remove the last leftovers from the old text. Also delete the temporary
markers added for the rewrite of this document. Add a SPDX tag with the
new license now that the rewrite is complete. Add a license hint whom to
attribute when distributing the text under CC-BY 4.0.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/admin-guide/reporting-bugs.rst | 27 ++++++--------------
 1 file changed, 8 insertions(+), 19 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 42f59419263a..bbddea6b1567 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -1,15 +1,10 @@
+.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
+
 .. _reportingbugs:
 
 Reporting bugs
 ++++++++++++++
 
-.. ############################################################################
-.. Temporary marker added while this document is rewritten. The sections below
-.. up to a second marker of this kind are new and dual-licensed under GPLv2+
-.. and CC-BY 4.0. Both sections are incomplete as of now and thus might be
-.. inconsistent/not make sense before all patches of the rewrite got applied.
-.. ###########################################################################
-
 
 The short guide (aka TL;DR)
 ===========================
@@ -1467,15 +1462,9 @@ document and the implications between the lines illustrate that. But that's how
 it is for now. The main author of this text hopes documenting the state of the
 art will lay some groundwork to improve the situation over time.
 
-.. ############################################################################
-.. 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.
-.. Both sections are incomplete as of now and thus sometimes inconsistent.
-.. ###########################################################################
-
-How to report Linux kernel bugs
-===============================
-
-Thank you!
-
-[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]
+*Licensing advice: This document is dual-licensed under GPL-2.0+ and CC-BY 4.0.
+If you want to distribute it under the terms of the latter, please use 'The
+Linux kernel developers' for author attribution and either
+https://www.kernel.org/doc/html/latest/admin-guide/reporting-bugs.html or
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-bugs.rst
+when pointing to the source.*
-- 
2.26.2

Re: [RFC PATCH v1 00/26] Make reporting-bugs easier to grasp and yet more detailed

[Thorsten Leemhuis]

Lo!

Am 01.10.20 um 10:39 schrieb Thorsten Leemhuis:
> This series rewrites the "how to report bugs to the Linux kernel maintainers"
> document to make it more straight forward and the essence easier to grasp. At
> the same time make the text provide a lot more details about the process in form
> of a reference section, so users that want or need to know them have them at
> hand.
> 
> The goal of this rewrite: improve the quality of the bug reports and reduce the
> number of reports that get ignored. This was motivated by many reports of poor
> quality the main author of the rewrite stumped upon when he was tracking
> regressions.

So, now that those weeks with the merge window, the OSS & ELC Europe, 
and this US election thing are behind us it seems like a good time to ask:

How to move on with this?

@Jon: I'd be really appreciate to hear your thoughts on this.

@Randy: Thx again for all suggestions and pointing out many spelling 
mistakes, that helped a lot! You didn't reply to some of the patches, 
which made me wonder: did you not look at those (which is totally fine) 
or was there nothing to point out? And what I'd really like to know: 
what are you thinking about the whole thing?

@Everyone: Yes, I know, the length of the text is a bit intimidating, 
but the structure was carefully chosen to get everything crucial across 
at the top quickly, to make sure impatient readers quickly find what 
they need -- and the details as well in later sections, in case they 
need them. Yes, sure, that is not easy to achieve, but I think having 
all the relevant information close together is of benefit for the 
readers. Keeping details out that a significant share of readers will 
likely need sounds a bit like saying "we don't take that patch, it for 
the embedded use case and we only care about desktops and server" to me 
(something which we don't do for good reasons and served us quite well 
afaics)[¹].

Ohh, and btw: I still look for any input of what to write in the "decode 
strack trace" section (see patch 19 you'll also find here
https://lore.kernel.org/lkml/fc63c021e58106559717fe1ecbbd24163e1c152d.1601541165.git.linux@leemhuis.info/
). Anyone seen some blog post or article that gives on the current state 
of the art that might get me started?

Ciao, Thorsten

[¹] Side note: I noticed I even forgot to describe one thing: how to 
join an existing mailing list discussion without breaking threading. 
That something that even experienced users sometimes have trouble with, 
afaics.


> For the curious, this is how the text looks in the end:
> https://gitlab.com/knurd42/linux/-/raw/reporting-bugs-rfc/Documentation/admin-guide/reporting-bugs.rst
> 
> For comparison, here you can find the old text and the commits to it and its
> predecessor:
> https://www.kernel.org/doc/html/latest/admin-guide/reporting-bugs.html
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-bugs.rst
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/Documentation/admin-guide/reporting-bugs.rst
> https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/REPORTING-BUGS
> 
> This is an early RFC and likely has some spelling and grammatical mistakes.
> Sorry for that, the main author is not a native English speaker and makes too
> many of those mistakes even in his mother tongue. He used hunspell and
> LanguageTool to find errors, but noticed those tools miss quite a few mistakes.
> Hopefully it's not too bad.
> 
> The main author of the rewrite is also fully aware the text got quite long in
> the end. That happened as he tried to make users avoid many of the problem he
> noticed in bug report, which needed quite a bit of space to describe.
> Nevertheless, he tried to make sure the text uses a structure where only those
> that want to know all the details have to read it. That's mainly realized with
> the help of the TL;DR and the short guide at the top of the document. Those
> should be good enough for a lot of situations.
> 
> There are a few points that will need to be discussed. The comment in the
> individual patches will point some of those out; that for example includes
> things like "dual licensing under CC-BY 4.0", "are we asking too much from users
> when telling them to test mainline?", and "CC LKML or something else on all
> reports?". But a few points are best raised here:
> 
>   * The old and the new reporting-bugs text take a totally different approach to
> bugzilla.kernel.org. The old mentions it as the place to file your issue if
> you don't know where to go. The new one mentions it rarely and most of the
> time warn users that it's often the wrong place to go. This approach was
> chosen as the main author noticed quite a few users (or even a lot?) get no
> reply to the bugs they file in bugzilla. That's kind of expected, as quite a
> few (many? most?) of the maintainers don't even get notified when reports for
> their subsystem get filed there. Anyway: not getting a reply is something
> that is just annoying for users and might make them angry. Improving bugzilla
> would be an option, but on the kernel and maintainers summit 2017 (sorry it
> took so long) it was agreed on to first go this route, as it's easier to
> reach and less controversial, as many maintainers likely are unwilling to
> deal with bugzilla.
> 
>   * The text states "see above" or "see below" in a few places. Should those be
> proper links? But then some anchors will need to be placed manually in a few
> places, which slightly hurt readability of the plain text. Could RST or
> autosectionlabel help here somewhat (without changing the line
> "autosectionlabel_maxdepth = 2" in Documentation/conf.py, which likely is
> unwanted)?
> 
>   * The new text avoids the word "bug" and uses "issues" instead, as users face
> issues which might or might not be caused by bugs. Due to this approach it
> might make sense to rename the document to "reporting-issues". But for now
> everything is left as it is, as changing the name of a well known file has
> downsides; but maybe at least the documents headline should get the
> s/bugs/issues/ treatment.
> 
>   * How to make sure everybody that cares get a chance to review this? As this is
> an early RFC, the author chose to sent it only to the docs maintainer,
> linux-docs and LKML, to see how well this approach is received in general.
> Once it is agreed that this is the route forward, a lot of other people need
> to be CCed to review it; the stable maintainers for example should check if
> the section on handling issues with stable and longterm kernels is acceptable
> for them. In the end it's something a lot of maintainers might want to take
> at least a quick look at, as they will be dealing with the reports. But there
> is no easy way to contact all of them (apart from CCing all of them), as most
> of them likely don't read LKML anymore. Should the author maybe abuse
> ksummit-discuss, as this likely will reach all the major stakeholders Side
> note: maybe it would be good to have a list for things like this on vger...
> 
> The patch series is against docs-next and can also be found on gitlab:
> git://git@gitlab.com:knurd42/linux.git reporting-bugs-rfc
> 
> Strictly speaking this series is not bisectable, as the old text it left in
> place and removed slowly by the patches in the series when they add new text
> that covers the same aspect. Thus, both old and new text are incomplete or
> inconsistent (and thus would not build, if we'd talked about code). But that is
> only relevant for those that read the text before the series is fully applied.
> That seemed like an acceptable downside in this case, as this makes it easier to
> compare the old and new approach.
> 
> Note: The main autor is not a developer, so he will have gotten a few things in
> the procedure wrong. Let him know if you spot something where things are off.
> 
> Thorsten Leemhuis (26):
>    docs: reporting-bugs: temporary markers for licensing and diff reasons
>    docs: reporting-bugs: Create a TLDR how to report issues
>    docs: reporting-bugs: step-by-step guide on how to report issues
>    docs: reporting-bugs: step-by-step guide for issues in stable &
>      longterm
>    docs: reporting-bugs: begin reference section providing details
>    docs: reporting-bugs: point out we only care about fresh vanilla
>      kernels
>    docs: reporting-bugs: let users classify their issue
>    docs: reporting-bugs: make readers check the taint flag
>    docs: reporting-bugs: help users find the proper place for their
>      report
>    docs: reporting-bugs: remind people to look for existing reports
>    docs: reporting-bugs: remind people to back up their data
>    docs: reporting-bugs: tell users to disable DKMS et al.
>    docs: reporting-bugs: point out the environment might be causing issue
>    docs: reporting-bugs: make users write notes, one for each issue
>    docs: reporting-bugs: make readers test mainline, but leave a loophole
>    docs: reporting-bugs: let users check taint status again
>    docs: reporting-bugs: explain options if reproducing on mainline fails
>    docs: reporting-bugs: let users optimize their notes
>    docs: reporting-bugs: decode failure messages [need help]
>    docs: reporting-bugs: instructions for handling regressions
>    docs: reporting-bugs: details on writing and sending the report
>    docs: reporting-bugs: explain what users should do once the report got
>      out
>    docs: reporting-bugs: details for issues specific to stable and
>      longterm
>    docs: reporting-bugs: explain why users might get neither reply nor
>      fix
>    docs: reporting-bugs: explain things could be easier
>    docs: reporting-bugs: add SPDX tag and license hint, remove markers
> 
>   Documentation/admin-guide/bug-bisect.rst      |    2 +
>   Documentation/admin-guide/reporting-bugs.rst  | 1586 +++++++++++++++--
>   Documentation/admin-guide/tainted-kernels.rst |    2 +
>   scripts/ver_linux                             |   81 -
>   4 files changed, 1441 insertions(+), 230 deletions(-)
>   delete mode 100755 scripts/ver_linux
> 
> 
> base-commit: e0bc9cf0a7d527ff140f851f6f1a815cc5c48fea
> 

Re: [RFC PATCH v1 00/26] Make reporting-bugs easier to grasp and yet more detailed

[Jonathan Corbet]

On Mon, 9 Nov 2020 12:01:56 +0100
Thorsten Leemhuis <linux@leemhuis.info> wrote:

> @Jon: I'd be really appreciate to hear your thoughts on this.

Seems like it's time to post a new version with all of your feedback so
far reflected, and we'll go from there?

Thanks,

jon

Re: [RFC PATCH v1 00/26] Make reporting-bugs easier to grasp and yet more detailed

[Thorsten Leemhuis]

Am 09.11.20 um 19:21 schrieb Jonathan Corbet:
> On Mon, 9 Nov 2020 12:01:56 +0100
> Thorsten Leemhuis <linux@leemhuis.info> wrote:
> 
>> @Jon: I'd be really appreciate to hear your thoughts on this.
> 
> Seems like it's time to post a new version with all of your feedback so
> far reflected, and we'll go from there?

Will do, just give me a day to two.

Ciao, Thorsten

P.S.: BTW, @Randy, thx for yesterdays clarification in another mail of 
this subthread!

Re: [RFC PATCH v1 00/26] Make reporting-bugs easier to grasp and yet more detailed

[Randy Dunlap]

On 11/9/20 3:01 AM, Thorsten Leemhuis wrote:
> Lo!
> 
> Am 01.10.20 um 10:39 schrieb Thorsten Leemhuis:
>> This series rewrites the "how to report bugs to the Linux kernel maintainers"
>> document to make it more straight forward and the essence easier to grasp. At
>> the same time make the text provide a lot more details about the process in form
>> of a reference section, so users that want or need to know them have them at
>> hand.
>>
>> The goal of this rewrite: improve the quality of the bug reports and reduce the
>> number of reports that get ignored. This was motivated by many reports of poor
>> quality the main author of the rewrite stumped upon when he was tracking
>> regressions.
> 
> So, now that those weeks with the merge window, the OSS & ELC Europe, and this US election thing are behind us it seems like a good time to ask:
> 
> How to move on with this?
> 
> @Jon: I'd be really appreciate to hear your thoughts on this.
> 
> @Randy: Thx again for all suggestions and pointing out many spelling mistakes, that helped a lot! You didn't reply to some of the patches, which made me wonder: did you not look at those (which is totally fine) or was there nothing to point out? And what I'd really like to know: what are you thinking about the whole thing?

Hi,

I looked at all of the patches in the series but did not have any comments
on the ones where I didn't reply.


thanks.

-- 
~Randy