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

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

[Thorsten Leemhuis]

This series rewrites the "how to report bugs to the Linux kernel
maintainers" document to make it more straight forward and its 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 submitter noticed while looking after Linux
kernel regression tracking many moons ago.

This is v2, but still RFC, as there are still quite a number of things to
discuss (see below). For the curious, this is how the text currently looks
in the end:
https://gitlab.com/knurd42/linux/-/raw/reporting-bugs-v2/Documentation/admin-guide/reporting-bugs.rst

The main author of this rewrite is fully aware the new text is quite long
and thus might look a bit intimidating. But the text's structure with a
TDLR, a step-by-step guide and a reference section was carefully crafted
to make sure the text can serve different needs depending on what readers
know about bug reporting and the linux kernel; that's why the text among
others can work for kernel developers that just need to look something up,
developers & experienced FLOSS contributors that are new to the kernel and
need a rough instructions, as well as Linux users that just want to report
a problem upstream. The text is thus a bit like the kernel itself, which
works well for small embedded machines, a typical desktop PC, cloud
servers, as well as HPC.

There are a few points that will need discussions which comments in the
individual patches will point out. That for example includes things like
"is dual licensing under CC-BY 4.0 a good idea", "are we asking too much
from users when telling them to test mainline?", and "create a mailing
list that should be CCed 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 achieve and less controversial, as
putting additional burden on already overworked maintainers is unlikely to
get well received.

 * The text states "see above" or "see below" in a few places. Should
those be proper links? But then anchors will need to be placed in some
places, which slightly hurt readability of the plain text version. Could
RST or autosectionlabel help here somewhat (without changing the line
"autosectionlabel_maxdepth = 2" in Documentation/conf.py, which I assume
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 a s/bugs/issues/ treatment.

 * How to make sure everybody that cares get a chance to review this? As
this still 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 parts of 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 many people), 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...

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.  And 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 here IMHO, as this makes it easier to compare the old and new
approach.

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

= Big outstanding issues =

 * is the general approach a good idea?
 * dedicated mailing lists for issues (see patch !!!)
 * input needed how to properly prepare and handle stack dumps these days
(see patch !!!)
 * should we accept reports for issues with kernel images
that are pretty close to vanilla? (see patch !!!) * linking back and forth
within the text?

= Changes =

v1 -> v2
 * all over: a whole lot of spelling fixes and small improvements. Many
thx to suggestions from Randy Dunlap (many thx!).
 * use "ref:" to reference MAINTAINERs file
 * the licensing advice is now a rst comment near the top
 * reshuffle and rewrite some parts to make them more straight forward:
  * The short guide (aka TL;DR)" (patch 2)
  * Locate kernel area that causes the issue (patch 9)
  * Install a fresh kernel for testing (patch 15)
 * to see all changes since v1 compare these two files with tool like meld
or kdiff3:
https://gitlab.com/knurd42/linux/-/raw/reporting-bugs/Documentation/admin-guide/reporting-bugs-v1.rst
https://gitlab.com/knurd42/linux/-/raw/reporting-bugs/Documentation/admin-guide/reporting-bugs-v2.rst

= Links =

v1:
https://lore.kernel.org/lkml/cover.1601541165.git.linux@leemhuis.info/

Current version of reporting-bugs.rst
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

Commits to it and its predecessor:
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

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 a fresh kernel
  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 is
    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  | 1652 +++++++++++++++--
 Documentation/admin-guide/tainted-kernels.rst |    2 +
 scripts/ver_linux                             |   81 -
 4 files changed, 1507 insertions(+), 230 deletions(-)
 delete mode 100755 scripts/ver_linux


base-commit: f8394f232b1eab649ce2df5c5f15b0e528c92091
-- 
2.28.0

[RFC PATCH v2 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 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, to make is obvious
that all old text got removed 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.28.0

[RFC PATCH v2 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 three paragraphs. The fourth is
dedicated to issues only happening in stable and longterm kernels, as
things otherwise get hard to follow.

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

v2: reshuffled and rewritten to make this section more straight forward
---
 Documentation/admin-guide/reporting-bugs.rst | 45 ++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 4bbb9132782b..97815a35c546 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -10,6 +10,51 @@ Reporting bugs
 .. inconsistent/not make sense before all patches of the rewrite got applied.
 .. ###########################################################################
 
+
+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 too complex. 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,
+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.
+
+
 .. ############################################################################
 .. 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.28.0

[RFC PATCH v2 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 issues 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 steps explain a few basics
that might seem natural to kernel developers, but are things that people
sometimes get wrong.

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

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 97815a35c546..a654c54d7dc6 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -55,6 +55,113 @@ If you reached this point without a solution, ask for advice one the
 subsystem's mailing list.
 
 
+Step-by-step guide how to report issues to the kernel maintainers
+=================================================================
+
+The 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 and leaves
+out a lot of details; those are described below the step-by-step guide in a
+reference section, which explains each of the steps 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 the latest mainline kernel already or are willing to
+   install it. This kernel must not be modified or enhanced in any way, and
+   thus be considered 'vanilla'.
+
+ * 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, 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. 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, which solutions like DKMS might be doing locally
+   without your knowledge.
+
+ * Make sure it's not the kernel's surroundings that are causing the issue
+   you face.
+
+ * Write down coarsely how to reproduce the issue. If you deal with multiple
+   issues 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 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.
+
+ * 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.
+
+ * 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 mention a few things: the latest kernel version you installed
+   for reproducing, the Linux Distribution used, and your notes on how to
+   reproduce the issue. Ideally, make the kernel's 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.
+
+ * 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: retest with at
+   least every first release candidate (RC) of a new mainline version and
+   report your results. Send friendly reminders if things stall. And try to
+   help yourself, if you don't get any help or if it's 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.28.0

[RFC PATCH v2 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
typical flow hard to understand.

Yet again a reference section will later describe each step in more
detail and repeat each step as introduction.

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

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index a654c54d7dc6..2b48c824d070 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -162,6 +162,54 @@ After these preparations you'll now enter the main part:
    help yourself, if you don't get any help or if it's 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 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 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; then check the discussions if the fix was
+   deemed unsuitable for backporting. If backporting was not considered at
+   all, join the newest discussion, asking if it's 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 who 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.28.0

[RFC PATCH v2 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>
---
v2:
- mention https://jvns.ca/blog/good-questions/

= 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 | 47 +++++++++++++++++---
 1 file changed, 41 insertions(+), 6 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 2b48c824d070..8993b4ccb0f0 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -210,6 +210,47 @@ rebased on new stable or longterm releases. If that case follow these steps:
    as the stable mailing list.
 
 
+Reference section: Reporting issues to the kernel maintainers
+=============================================================
+
+The detailed guides above outline all the major 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
+above steps. Consider this as reference documentation: it's possible to read it
+from top to bottom. But it's mainly meant to skim over and a place to look up
+details how to actually perform those steps.
+
+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 some infrastructure,
+   which 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 vendor's 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>`_, `How To Ask
+   Questions The Smart Way
+   <http://www.catb.org/esr/faqs/smart-questions.html>`_, and `How to ask good
+   questions <https://jvns.ca/blog/good-questions/>`_.
+
+With that off 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.
@@ -286,12 +327,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.28.0

[RFC PATCH v2 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: 4556 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 (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. This should help to reduce that. It also
explains the reasons, as some users otherwise might think "why do kernel
devs makes things so complicated for me".

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 individual issue and the
involved developers, as some expect tests with a frehs vanilla mainline
kernel. That's why installing one is the safe bet.```
---
 Documentation/admin-guide/reporting-bugs.rst | 35 ++++++++++++++++----
 1 file changed, 29 insertions(+), 6 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 8993b4ccb0f0..9122889509de 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -251,6 +251,35 @@ With that off 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 the latest mainline kernel already or are willing to
+   install it. This kernel must not be modified or enhanced in any way, and
+   thus be considered 'vanilla'.*
+
+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. In practice that sometimes does not work out. If
+that the case, you might want to circumvent the vendor by installing the latest
+mainline kernel yourself and reporting the issue as outlined in this document;
+just make sure to use really fresh kernel (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.
@@ -268,12 +297,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.28.0

[RFC PATCH v2 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 9122889509de..fdd79d99c18f 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -280,6 +280,45 @@ mainline kernel yourself and reporting the issue as outlined in this document;
 just make sure to use really fresh kernel (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 there are 'issues of high priority' that get
+handled slightly differently 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 WiFi 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 built with a configuration that is similar to the one
+from the old kernel (see below how to achieve that). That's because the kernel
+developers sometimes can not avoid incompatibilities when implementing new
+features; but to avoid regressions such features 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 unacceptably 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 confuse a 'panic' (a
+fatal error where the kernel stop itself) with a 'Oops' (a recoverable error),
+as the kernel remains running after the latter.
+
+
 .. ############################################################################
 .. 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.28.0

[RFC PATCH v2 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 easily mix things up.
---
 Documentation/admin-guide/reporting-bugs.rst  | 69 +++++++++++++++++++
 Documentation/admin-guide/tainted-kernels.rst |  2 +
 2 files changed, 71 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index fdd79d99c18f..8ac491419bde 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -319,6 +319,75 @@ fatal error where the kernel stop itself) with a 'Oops' (a recoverable error),
 as the kernel remains running after the latter.
 
 
+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; you will need to check the taint flag again
+then, as that's when it matters because it's the kernel the report will focus
+on.
+
+On a running system is easy to check if the kernel tainted itself: if ``cat
+/proc/sys/kernel/tainted`` returns '0' then the kernel is not tainted and
+everything is fine. 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 when it noticed the problem; 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. Try to eliminate the reason. Often it's caused by one these three
+things:
+
+ 1. 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 happens after that point might be a
+    follow-up problem to that first Oops, even if both look totally unrelated.
+    Rule this out by getting rid of the cause for the first 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.
+
+ 2. Your system uses a software that installs its own kernel modules, for
+    example Nvidia's proprietary graphics driver or VirtualBox. The kernel
+    taints itself when it loads such module from external sources (even if
+    they are Open Source): they sometimes cause errors in unrelated kernel
+    areas and thus might be causing the issue you face. You therefore have to
+    prevent those modules from loading when you want to report an issue to the
+    Linux kernel developers. Most of the time the easiest way to do that is:
+    temporarily uninstall such software including any modules they might have
+    installed. Afterwards reboot.
+
+ 3. The kernel also taints itself when it's loading a module that resides 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 temporarily 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 f718a2eaf1f6..04d8da1fc080 100644
--- a/Documentation/admin-guide/tainted-kernels.rst
+++ b/Documentation/admin-guide/tainted-kernels.rst
@@ -1,3 +1,5 @@
+.. _taintedkernels:
+
 Tainted kernels
 ---------------
 
-- 
2.28.0

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

[Thorsten Leemhuis]

Make it obvious that bugzilla.kernel.org most of the time is the wrong
place to file a report, as it's not working well. Instead, tell users
how to read the MAINTAINERS file to find the proper place for their
report. Also mention ./scripts/get_maintainer.pl. Sadly this is only
available for users that have the sourced at hand; in an ideal world
somebody would build a web-service around of this.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
v2:
- partly rewritten after some comments from Randy

= RFC =

I think we should create mailing list like
'linux-issues@vger.kernel.org' and tell users here to always CC it when
reporting issues. Then they'd have one place they can search in case
they want to check for existing reports (at least for issues reported by
mail).

Note, this section tells users to always CC LKML. These days it's a kind
of "catch-all" list anyway (which nearly nobody reads). So it IMHO makes
sense to go "all in" and make people send their reports here, too, as
everything (reports, fixes, ...) then can be found in one place (at
least for all reports sent by mail and all subsystems that CC LKML).
---
 Documentation/admin-guide/reporting-bugs.rst | 187 ++++++++++++++-----
 1 file changed, 142 insertions(+), 45 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 8ac491419bde..9e0e9b2ba27b 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -388,6 +388,148 @@ things:
     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 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 remote or unrelated "subsystems", like the TCP
+stack, the PCIe/PCI subsystem, memory management or file systems.
+
+Problem is: the Linux kernel lacks a central bug tracker where you can simply
+file your issue and make it 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 (see below), 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. If it's really something else, the driver's developers will get the
+right people involved.
+
+Sadly, there is no way to check which code is driving a particular hardware
+component that is both universal and easy.
+
+In case of a problem with the WiFi driver 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
+guessed 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 for help;
+but before doing so, try a somewhat shorted or modified name when searching the
+MAINTAINERS file, 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:'.
+A section near the top of the file explains these and other abbreviations.
+
+First look at the line 'Status'. Ideally it should be 'Supported' or
+'Maintained'. If it states 'Obsolete' then you are using some outdated approach
+that was replaced by a newer solution you need to switch to. Sometimes the code
+only has someone who provides 'Odd Fixes' when feeling motivated. And with
+'Orphan' you are totally out of luck, as nobody takes care of the code anymore.
+That only leaves these options: arrange yourself to 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. Very few subsystems use
+a bug tracker, and only some of those rely on bugzilla.kernel.org.
+
+In this and 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: the script 'scripts/get_maintainer.pl' which tries
+to find all people to contact. It queries the MAINTAINERS file and 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. Send it to the maintainers, which the
+script calls "supporter:"; additionally CC the most specific mailing list for
+the code as well as the 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 these results with care, as it
+can easily send you in a wrong direction. That for example happens quickly in
+areas rarely changed (like old or unmaintained drivers): sometimes such code is
+modified during tree-wide cleanups by developers that do not care about the
+particular driver at all.
+
+
 .. ############################################################################
 .. 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.
@@ -410,51 +552,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.28.0

[RFC PATCH v2 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. Tell 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 could benefit from a detailed description.
---
 Documentation/admin-guide/reporting-bugs.rst | 59 ++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 9e0e9b2ba27b..455d67be0fd7 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -530,6 +530,65 @@ modified during tree-wide cleanups by developers that do not care about the
 particular driver at all.
 
 
+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 WiFi 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: most subsystems expect reports in different
+places, hence those you find there might have not even reached the people
+responsible for the subsystem in question. Nevertheless, the data there might
+provide valuable insights.
+
+If you get flooded with results consider telling your search engine to limit
+search timeframe to 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 the perspective of someone else: that will help you to
+come up with other words to use as search terms. Also make sure not to 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, as it is too specific. Instead try search terms like
+the model line (Radeon 5700 or Radeon 5000) and the code name of the main chip
+('Navi' or 'Navi10') with and without its manufacturer ('AMD').
+
+In case you find an existing report about your issue, join 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. Jump to the section 'Duties after the report went out' for
+details on 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.28.0

[RFC PATCH v2 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 if 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 455d67be0fd7..8633f0976b00 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -589,6 +589,19 @@ test a proposed fix. Jump to the section 'Duties after the report went out' for
 details on 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, which 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.28.0

[RFC PATCH v2 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 kernel they
install later remains vanilla. The old text did not do that, but such
solutions were not that widespread back when it was written.

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

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 8633f0976b00..5f6d3b2b55f9 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -602,6 +602,28 @@ 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, which solutions like DKMS might be doing locally
+    without your knowledge.*
+
+Your kernel must be 'vanilla' when reporting an issue, but stops being pure as
+soon as it loads a kernel module not built from the sources used to compile the
+kernel image itself. That's 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 Nvidia's proprietary graphics
+driver, VirtualBox, or other software that requires a some support from a
+module not part of the Linux kernel. That why your might need to uninstall the
+packages with such software to get rid of any 3rd party kernel module.
+
+
 .. ############################################################################
 .. 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.28.0

[RFC PATCH v2 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 | 35 ++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 5f6d3b2b55f9..234731cd0c78 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -624,6 +624,41 @@ module not part of the Linux kernel. That why your might need to uninstall the
 packages with such software to get rid of any 3rd party kernel module.
 
 
+Ensure a healthy environment
+----------------------------
+
+    *Make sure it's not the kernel's 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 run within their design specifications;
+   that's especially important for the main processor, the main memory, and the
+   motherboard. Therefore, stop undervolting or 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``, as it might be damaged in a way that leads
+   to unexpected kernel behavior.
+
+ * 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 other 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 look a lot
+   like a kernel 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.28.0

[RFC PATCH v2 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 a
fresh kernel later in the process. At the same time the notes 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 | 36 +++++++++++++++-----
 1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 234731cd0c78..981ddd5a0646 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -659,6 +659,33 @@ should minimize it:
    like a kernel regression.
 
 
+Document how to reproduce issue
+-------------------------------
+
+    *Write down coarsely how to reproduce the issue. If you deal with multiple
+    issues 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 issues 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 very 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 an issue quickly on a freshly booted system.
+
+Note: it's often fruitless to report 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. Feel free
+to ignore this advice 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.
@@ -681,15 +708,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.28.0

[RFC PATCH v2 15/26] docs: reporting-bugs: make readers test a fresh kernel

[Thorsten Leemhuis]

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

Now that the document described all preparatory steps tell users to
install a really fresh kernel. The text tries pretty hard motivating
them to install 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>
---

v2: reshuffled and rewritten to make this section more straight forward

= 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 | 103 +++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 981ddd5a0646..506292ab9bb6 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -686,6 +686,109 @@ due to faulty hardware apart from a kernel issue that rarely happens and thus
 is hard to reproduce.
 
 
+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 developers first apply fixes; only after that are 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. 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:
+
+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, 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 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 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-built or self-compiled kernel for testing; if you choose 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 get released at least once a week. And be aware that
+you might need to get build your own kernel later anyway when it comes to
+helping 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 isnot 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.
+
+
 .. ############################################################################
 .. 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.28.0

[RFC PATCH v2 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 | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 506292ab9bb6..e9fe40a96b87 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -789,6 +789,20 @@ somewhat for your system. That does not make the resulting kernel any better,
 but quicker to compile.
 
 
+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.28.0

[RFC PATCH v2 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 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index e9fe40a96b87..60a84f52724c 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -803,6 +803,23 @@ eliminate the reason 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.*
+
+Check if the issue occurs with the fresh Linux kernel version you just
+installed. If it was fixed there already, consider sticking with this version
+line and abandoning your plan to report the issue. But keep in mind that other
+users might still 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 or just want to 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.28.0

[RFC PATCH v2 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 people recheck and
optimize their notes how to reproduce the issue. It's also a good moment
to make them search again for existing reports, as they might have
learned something in the previous steps.

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

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 60a84f52724c..7af4e7a6e797 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -820,6 +820,25 @@ 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 will make it hard for others to understand your
+report. Thus try to find a reproducer that's straight forward to describe and
+thus easy to understand in written form. 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.28.0

[RFC PATCH v2 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 (when is scripts/decode_stacktrace.sh
enough?), 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 (CONFIG_UNWINDER_ORC when available, otherwise
CONFIG_UNWINDER_FRAME_POINTER)?".

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 7af4e7a6e797..be866dd1e6b6 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -839,6 +839,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.
@@ -870,9 +882,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.28.0

[RFC PATCH v2 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 | 54 ++++++++++++++++++++
 2 files changed, 56 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 be866dd1e6b6..6646d393f21a 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -851,6 +851,60 @@ 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 change that's causing
+the regression needs to be known. Normally it's up to the reporter to track
+down the culprit, as maintainers often won't have the time or setup at hand to
+reproduce it themselves.
+
+To find the change 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, trying to reproduce the issue with each of them before building the
+next. Yes, that takes some time, 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 find it, search 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 existing 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 makes the outcome hard to
+interpret, which might render your testing useless. Once you found the major
+version which introduced the regression, feel free to move on in the reporting
+process. But keep in mind: it depends on the issue at hand if the developers
+will be able to help without knowing the culprit. Sometimes they might
+recognize from the report want went wrong and can fix it; other times they will
+be unable to help unless you perform 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 built with a similar configuration. The best way
+to archive this: copy the configuration file (``.config``) from the old working
+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.28.0

[RFC PATCH v2 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: 18110 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 approach the
old text used: it 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 and hard to compile.

That's also why this commit removes scripts/ver_linux as well: the
details it collects are only needed in some situations. And some (a
lot?) distributions do not ship it anyway; a better, more modern script
would likely resist in tools/, which would increase chances that distros
shipping it as part of 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 6646d393f21a..71d499cc47fe 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -905,6 +905,204 @@ oldnoconfig`` to adjust it for the needs of the new version without 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 mention a few things: the latest kernel version you installed
+    for reproducing, the Linux Distribution used, and your notes on how to
+    reproduce the issue. Ideally, make the kernel's 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 three documents linked to in the preface above.
+That's why this text will only mention a few of the essentials as well as
+things 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. They thus often just take a few
+seconds to skim a mail before deciding to move on or look closer. 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 is 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 outline 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 change that is causing it.
+
+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 kernel's messages that you get from ``dmesg`` written to a file. Make
+   sure that it starts with 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' If it's missing, then important messages from the first
+   boot phase already got discarded. In this case instead consider using
+   ``journalctl -b 0 -k``; alternatively you can also reboot, reproduce the
+   issue and call ``dmesg`` right afterwards.
+
+These two 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 five or ten years from now a developer works on some code that was
+   changed just 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 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 at least 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, the card's model, and what chip is uses. 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 looks
+   not that different from 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 model name or specify the main components.
+
+ * Mention the relevant software in use. 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>`_.
+
+Those examples should give your some ideas of what data might be wise to
+attach, but you have to think yourself what will be helpful for others to know.
+Don't worry too much about forgetting something, as 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 to the
+most important section: the first few sentences. Thus go to the top, add
+something like 'The detailed description:' before the part you just 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 shorter 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 spent.
+
+Now send or file the report like the :ref:`MAINTAINERS <maintainers>` file told
+you, unless it's one of those 'issues of high priority' outlined earlier: in
+that case please read the next subsection first before sending the report on
+its way.
+
+Special handling for high priority issues
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Reports for high priority issues need special handling.
+
+**Severe bugs**: make sure the subject or ticket title as well as the first
+paragraph makes the severeness obvious.
+
+**Regressions**: If the issue is a regression add [REGRESSION] to the 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.
+
+**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 also 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. If you filed it in a bug tracker, forward
+the report's text to these addresses; 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.
@@ -927,55 +1125,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.28.0

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

[Thorsten Leemhuis]

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

Users should know that sending the report is not the end of this
process: if they want to see the issue fixed, they will often need to
keep the ball rolling. Hence, explain why it's in their interest to send
a reminder occasionally. Also point out that it's wise to retest after
every merge window.

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 "You should reply to every issue report at least once, ideally
within 1 to 5 business days"?
---
 Documentation/admin-guide/reporting-bugs.rst | 231 +++++++++++++++----
 1 file changed, 189 insertions(+), 42 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 71d499cc47fe..f455329063eb 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -1103,6 +1103,195 @@ See :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` for more
 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: retest with at
+    least every first release candidate (RC) of a new mainline version and
+    report your results. Send friendly reminders if things stall. And try to
+    help yourself, if you don't get any help or if it's 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 send 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 situations,
+but often it will be the things listed below. But before digging into the
+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 you filed the issue in a bug tracker, always
+reply there and do not contact any of the developers 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 stays in the loop; it
+also keeps the mail thread intact, which among others is really important for
+mailing lists 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 send something, but noticed it contains sensitive
+   information that needs to be kept private. In that case it's okay to send it
+   in private to the developer that asked for it. But note in the ticket or a
+   mail that you did that, so everyone else knows you honored the request.
+
+**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 be asked to use some test tools
+you never have heard of yet; or you might be 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 in other places for advice. For example ask a fried or post
+about it to a chatroom or forum you normally hang out.
+
+**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 night 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 the merge
+windows, 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: 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 get a higher authority involved. 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.
+
+**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
+mail you sent as reply to your 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, rc5 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 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. By doing this 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 without leading to a satisfying solution for the
+issue.
+
+**Inquiries for data**: Often you will be asked to test something or provide
+additional details. Try to provide the requested information 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 are asked to test a diagnostic patch or a
+possible fix, try to test it in timely manner, too. But do it properly and make
+sure to not rush it: mixing things up can happen easily and can lead to a lot
+of confusion for everyone involved. A common mistake for example is thinking a
+proposed patch with a fix was applied, but in fact wasn't. Things like that
+happen even to experienced testers occasionally, but they most of the time will
+notice when the kernel with the fix behaves just as one without it.
+
+What to do when nothing of substance happens
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some reports will not get any reaction from the responsible Linux kernel
+developers; or a discussion around the issue evolved, but faded out with
+nothing of substance coming 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 opinion. 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 send it out. Such an approach is totally fine; just
+mention 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 and provide a status update 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 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 it
+comes to Linux kernel development. This and several 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 find any help or if the issue in the end does
+not get solved: the Linux kernel is FLOSS and thus you can still help yourself.
+You for example could try to find others that are affected and team up with
+them to get the issue resolved. Such a team could 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.
@@ -1124,48 +1313,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.28.0

[RFC PATCH v2 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 a
lot 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 and explain how each of them
needs to be handled.

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

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index f455329063eb..ad9a5d896728 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -1292,24 +1292,187 @@ 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.
 
 
+Details about reporting issues only occurring in older kernel version lines
+---------------------------------------------------------------------------
+
+This subsection provides details for steps you need to take if you could not
+reproduce your issue with a mainline kernel, but want to see it fixed in older
+version lines (aka 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. Other 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 that won be backported to the
+version line your care about. In that case you'll have no other choice then to
+live with the issue or switch to a newer Linux version, unless you want to
+patch the fix into your kernels yourself.
+
+Make sure the particular version line still gets support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    *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 developers still support the version line you care
+for.
+
+Note, if kernel.org lists two 'stable' version lines on the front page, you
+should consider switching to the newer one and forget about the older one:
+support for it is likely to be abandoned soon. Then it will get a "end-of-life"
+(EOL) stamp. Version lines that reached that point still get mentioned on the
+kernel.org front page for a week or two, but 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 process 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; then check the discussions if the fix was
+    deemed unsuitable for backporting. If backporting was not considered at
+    all, join the newest discussion, asking if it's 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's why you want to search for it or any
+discussions abound it.
+
+ * First try to find the fix in 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 who 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 is 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 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
+to the stable maintainers, the stable mailing list, which the :ref:`MAINTAINERS
+<maintainers>` file 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 :ref:`MAINTAINERS
+<maintainers>` file 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.28.0

[RFC PATCH v2 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: 4663 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 will then be less disappointed if it happens to them.

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

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index ad9a5d896728..446c02e94c93 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -1467,6 +1467,63 @@ for the subsystem as well as the stable mailing list the :ref:`MAINTAINERS
 <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' (regressions, security issues, 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: sometimes 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. Sometimes developer stops caring for their code and Linux at all, as
+something different in their life became way more important. In some cases
+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 their code or make its
+programmer focus on other things. 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
+stopped selling years ago. Enterprise Linux distributors often care for a
+longer time period, but in new versions often leave support for old and rare
+hardware aside to limit the scope. Often spare time contributors take over once
+a company orphans some code, but as mentioned above: sooner or 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 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.
-- 
2.28.0

[RFC PATCH v2 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.

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 446c02e94c93..592329afc2a5 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -1524,6 +1524,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 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.
-- 
2.28.0

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

[Thorsten Leemhuis]

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

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 | 29 ++++++--------------
 1 file changed, 9 insertions(+), 20 deletions(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 592329afc2a5..6372800769e7 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -1,15 +1,17 @@
+.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
+..
+   If you want to distribute this document under the CC-BY-4.0, 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.
+
 .. _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)
 ===========================
@@ -1532,16 +1534,3 @@ 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.
-.. 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]
-- 
2.28.0

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

[Jonathan Corbet]

On Thu, 12 Nov 2020 18:58:37 +0100
Thorsten Leemhuis <linux@leemhuis.info> wrote:

> This series rewrites the "how to report bugs to the Linux kernel
> maintainers" document to make it more straight forward and its 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 submitter noticed while looking after Linux
> kernel regression tracking many moons ago.

So I've not had a chance to try to read through the whole thing again,
will try to do so in the near future.

As for how to proceed...getting others to review this is going to be a bit
of a challenge.  Perhaps the right approach is to just merge the new
document under a new name - reporting-bugs-the-novel.txt or something -
then try to get a few people to look at specific parts of it?  Once all
seems well we can rename it over the old document and call it done.

Make sense?

Thanks,

jon

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

[Randy Dunlap]

On 11/13/20 2:33 PM, Jonathan Corbet wrote:
> On Thu, 12 Nov 2020 18:58:37 +0100
> Thorsten Leemhuis <linux@leemhuis.info> wrote:
> 
>> This series rewrites the "how to report bugs to the Linux kernel
>> maintainers" document to make it more straight forward and its 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 submitter noticed while looking after Linux
>> kernel regression tracking many moons ago.
> 
> So I've not had a chance to try to read through the whole thing again,
> will try to do so in the near future.
> 
> As for how to proceed...getting others to review this is going to be a bit
> of a challenge.  Perhaps the right approach is to just merge the new
> document under a new name - reporting-bugs-the-novel.txt or something -
> then try to get a few people to look at specific parts of it?  Once all
> seems well we can rename it over the old document and call it done.
> 
> Make sense?

I like that idea.

I don't plan to review the series in detail like I did with v1.

-- 
~Randy

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

[Thorsten Leemhuis]

Am 13.11.20 um 23:33 schrieb Jonathan Corbet:
> On Thu, 12 Nov 2020 18:58:37 +0100
> Thorsten Leemhuis <linux@leemhuis.info> wrote:
> 
>> This series rewrites the "how to report bugs to the Linux kernel
>> maintainers" document to make it more straight forward and its 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 submitter noticed while looking after Linux
>> kernel regression tracking many moons ago.
> 
> So I've not had a chance to try to read through the whole thing again,
> will try to do so in the near future.

Great, thx, looking forward to it.

> As for how to proceed...getting others to review this is going to be a bit
> of a challenge.

Yeah :-/

>  Perhaps the right approach is to just merge the new
> document under a new name - reporting-bugs-the-novel.txt

drivers/staging/Documentation/ (no, just kidding [I think…])

>  or something -
> then try to get a few people to look at specific parts of it?  Once all
> seems well we can rename it over the old document and call it done.
> 
> Make sense?

Totally fine for me. Putting it some place that makes it easier to 
collaborate and to see who writes what is better for everyone – and get 
control out of my hands and burden off my shoulders. ;-)


There is just one thing on I'm wondering: should we start with the 
version of the text start users very long lines/is unwrapped and use it 
for the reviewing and polishing phase? Together with tools like meld of 
kdiff3 that afaics makes it lot easier to see what actually changes. 
That'd why I uploaded the text in such a format:

https://gitlab.com/knurd42/linux/-/raw/reporting-bugs/Documentation/admin-guide/reporting-bugs-v1.rst
https://gitlab.com/knurd42/linux/-/raw/reporting-bugs/Documentation/admin-guide/reporting-bugs-v2.rst

These for example would have allowed an easier rereview from Randy (but 
I think he's right not doing one right now [see the other reply]!), as 
these tools are quite well at highlighting what changed and what did 
not. Yer, these tools are not as bad as a classic diff once you change 
something in a wrapped paragraph, but in my experience work quite a bit 
better with long lines. That's why I wonder if we should stick to them 
before we call the main work done. Another reasons: with long lines 
everyone can temporarily put the text in LibreOffice, Google Docs, ... 
and use their spelling and grammar checkers.


Another aspect on my mind: the split up makes it easy to just CC certain 
people on parts we want them to review. I for example planned to CC the 
members of the stable-team only on four patches (TLDR, the two patches 
with the step by step parts, the reference section for stable and 
logterm), as those are the main ones that are relevant for them:

https://lore.kernel.org/lkml/b80b1387cf09fb897f4a527bc487fff3012d1181.1605203187.git.linux@leemhuis.info/
https://lore.kernel.org/lkml/b439c3d74c541d4d7631203a52f9d697ea8c283d.1605203187.git.linux@leemhuis.info/
https://lore.kernel.org/lkml/2d840fb91b7c5d481284275dea1d4f75fd755af6.1605203187.git.linux@leemhuis.info/
https://lore.kernel.org/lkml/0bb6bf554ac1f0c2a75631e6969a50dcd34c6b51.1605203187.git.linux@leemhuis.info/

Without a split split we'd have to tell people something like "please 
took at the document <here> and the sections starting with <foo>, <bar>, 
and <baz>". Or would we at some point just simply sent those parts as 
regular text (not as diff) my mail to the people & lists that need to 
review them?


And a few more thoughts, just for completeness.

* I guess we should discuss the dual-license approach I chose soon 
before it gets complicate to change it

* Some of the reviewer might want to compare the approaches the old and 
the new text take. The current patch-series tries to makes that easy by 
removing parts from the old text when adding new text about that topic. 
That would be mostly lost afaics, but I guess it's not that much of a 
problem.

* I wonder if putting the text in some real collaborative text editor 
(google docs, a wiki, Etherpad, …) for a while would be even better. But 
even with restricted write access that might pose some problems for 
signing the changes off later. :-/ Guess finding the solution for those 
might not be worth the trouble.

Ciao, Thorsten

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

[Jonathan Corbet]

On Thu, 12 Nov 2020 18:58:45 +0100
Thorsten Leemhuis <linux@leemhuis.info> wrote:

> +If your kernel is tainted, study
> +:ref:`Documentation/admin-guide/tainted-kernels.rst <taintedkernels>` to find
> +out why. Try to eliminate the reason. Often it's caused by one these three
> +things:

One little detail that jumped at me just now: the automarkup extension now
understands Documentation/whatever and makes a cross-reference, so there's
no need for an explicit :ref: for those.

Thanks,

jon

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

[Jonathan Corbet]

On Thu, 12 Nov 2020 18:58:58 +0100
Thorsten Leemhuis <linux@leemhuis.info> wrote:

> That's also why this commit removes scripts/ver_linux as well: the
> details it collects are only needed in some situations. And some (a
> lot?) distributions do not ship it anyway; a better, more modern script
> would likely resist in tools/, which would increase chances that distros
> shipping it as part of packages like "linux-tools".

Unless you're really sure that nobody us using this script, for whatever
reason, you can't really delete it, though.  It's been patched a couple of
times this year, so somebody is paying attention.  Probably safest to just
leave it there.

jon

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

[Jonathan Corbet]

On Sun, 15 Nov 2020 11:13:52 +0100
Thorsten Leemhuis <linux@leemhuis.info> wrote:

> > So I've not had a chance to try to read through the whole thing again,
> > will try to do so in the near future.  
> 
> Great, thx, looking forward to it.

OK, I have made a *quick* pass through the whole thing and sent a small
number of comments separately. There are things that could be tweaked
(there always will be) but I'm not sure we should worry about those yet.
I would suggest doing this:

 - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
   (or some suitable name).  I do wonder if it should also move to the
   process manual as part of this; not only admins will report bugs.

 - Add a comment at the top saying it's a proposed replacement and
   soliciting comments.  You could also put some of your other questions
   into the text for now and see if anybody reacts.  

 - In a separate patch you could add a comment to the existing document
   pointing to the new one as the true source of wisdom.

 - Dual licensed CC-SA-4.0 is fine with me.  CC-BY is OK if you really
   want to do it that way.  Either way, though, you'll need to add the
   license itself under LICENSES/preferred before it can go into the SPDX
   tag.

With that, I'd say let's just merge it and bash on it from there.

Thanks,

jon

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

[Thorsten Leemhuis]

Am 19.11.20 um 01:17 schrieb Jonathan Corbet:
> On Thu, 12 Nov 2020 18:58:58 +0100
> Thorsten Leemhuis <linux@leemhuis.info> wrote:
> 
>> That's also why this commit removes scripts/ver_linux as well: the
>> details it collects are only needed in some situations. And some (a
>> lot?) distributions do not ship it anyway; a better, more modern script
>> would likely resist in tools/, which would increase chances that distros
>> shipping it as part of packages like "linux-tools".
> 
> [...] It's been patched a couple of
> times this year, so somebody is paying attention.

Ugh, why haven't I checked for this? Argh :-/

>  Probably safest to just leave it there.

Agreed, thx for pointing it out.

Ciao, Thorsten

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

[Thorsten Leemhuis]

Am 19.11.20 um 01:05 schrieb Jonathan Corbet:
> On Thu, 12 Nov 2020 18:58:45 +0100
> Thorsten Leemhuis <linux@leemhuis.info> wrote:
> 
>> +If your kernel is tainted, study
>> +:ref:`Documentation/admin-guide/tainted-kernels.rst <taintedkernels>` to find
>> +out why. Try to eliminate the reason. Often it's caused by one these three
>> +things:
> 
> One little detail that jumped at me just now: the automarkup extension now
> understands Documentation/whatever and makes a cross-reference, so there's
> no need for an explicit :ref: for those.

Ha, cool, thx for the tip, will adjust accordingly!

Ciao, Thorsten

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

[Thorsten Leemhuis]

Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
> On Sun, 15 Nov 2020 11:13:52 +0100
> Thorsten Leemhuis <linux@leemhuis.info> wrote:
> 
>>> So I've not had a chance to try to read through the whole thing again,
>>> will try to do so in the near future.
>> Great, thx, looking forward to it.
> OK, I have made a *quick* pass through the whole thing and sent a small
> number of comments separately.

Great, thx, much appreciated.

> There are things that could be tweaked
> (there always will be) but I'm not sure we should worry about those yet.
> I would suggest doing this:
> 
>   - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
>     (or some suitable name).

Maybe just "reporting-issues.rst" or "reporting-issues-wip.rst". The 
text talks about issues anyway and rarely uses the word "bug".

>  I do wonder if it should also move to the
>     process manual as part of this; not only admins will report bugs.


I had wondered about this myself a few weeks ago, but I assumed someone 
had good reasons to put it in the admin section.

/me looks closer

Hmmm, now I'm unsure myself where to place it:

  * Documentation/admin/ is introduced as "The Linux kernel user’s and 
administrator’s guide" 
(https://www.kernel.org/doc/html/latest/admin-guide/). So maybe it's the 
right place that just uses a directory name that's easily misunderstood :-/

  * the process section starts with the words "So you want to be a Linux 
kernel developer? Welcome!" 
(https://www.kernel.org/doc/html/latest/process/). That might be a bit 
intimidating for people that just want to report a bug.

I guess it's best if you decide.

>   - Add a comment at the top saying it's a proposed replacement and
>     soliciting comments.  You could also put some of your other questions
>     into the text for now and see if anybody reacts.
> 
>   - In a separate patch you could add a comment to the existing document
>     pointing to the new one as the true source of wisdom.

Will do.

>   - Dual licensed CC-SA-4.0 is fine with me.  CC-BY is OK if you really
>     want to do it that way.  

I'm unsure and would appreciate options from others here.

Here are some of my thoughts about this:

What do we loose by dual-licensing it under a liberal license like 
CC-BY? It afaics makes it a lot more attractive for websites or books 
authors to use this text as a base, as they don't need to fear that 
"share alike" or the GPL might have consequences on the surroundings. 
I'd say that's a good thing for the kernel, as it increases the chances 
the texts built upon ours remain close to what we expect on this topic.

That's why I currently think using CC-BY is a good idea.

> Either way, though, you'll need to add the
>     license itself under LICENSES/preferred before it can go into the SPDX
>     tag.

Agh, yes, of course, will keep it in mind when above point is settled.

Ciao, Thorsten

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

[Randy Dunlap]

On 11/19/20 4:29 AM, Thorsten Leemhuis wrote:
> Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
>> On Sun, 15 Nov 2020 11:13:52 +0100
>> Thorsten Leemhuis <linux@leemhuis.info> wrote:
>>
>>>> So I've not had a chance to try to read through the whole thing again,
>>>> will try to do so in the near future.
>>> Great, thx, looking forward to it.
>> OK, I have made a *quick* pass through the whole thing and sent a small
>> number of comments separately.
> 
> Great, thx, much appreciated.
> 
>> There are things that could be tweaked
>> (there always will be) but I'm not sure we should worry about those yet.
>> I would suggest doing this:
>>
>>   - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
>>     (or some suitable name).
> 
> Maybe just "reporting-issues.rst" or "reporting-issues-wip.rst". The text talks about issues anyway and rarely uses the word "bug".
> 
>>  I do wonder if it should also move to the
>>     process manual as part of this; not only admins will report bugs.
> 
> 
> I had wondered about this myself a few weeks ago, but I assumed someone had good reasons to put it in the admin section.
> 
> /me looks closer
> 
> Hmmm, now I'm unsure myself where to place it:
> 
>  * Documentation/admin/ is introduced as "The Linux kernel user’s and administrator’s guide" (https://www.kernel.org/doc/html/latest/admin-guide/). So maybe it's the right place that just uses a directory name that's easily misunderstood :-/
> 
>  * the process section starts with the words "So you want to be a Linux kernel developer? Welcome!" (https://www.kernel.org/doc/html/latest/process/). That might be a bit intimidating for people that just want to report a bug.
> 
> I guess it's best if you decide.
I prefer to leave it in /admin-guide/.

-- 
~Randy

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

[Thorsten Leemhuis]

Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
> On Sun, 15 Nov 2020 11:13:52 +0100
> Thorsten Leemhuis <linux@leemhuis.info> wrote:

>   - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
>     (or some suitable name).  I do wonder if it should also move to the
>     process manual as part of this; not only admins will report bugs.

After a night's sleep and Randy's comment I for now settled on
Documentation/admin-guide/reporting-issues.rst

>   - Add a comment at the top saying it's a proposed replacement and
>     soliciting comments.  [...]
Struggled a bit to find the right words, but I think this should work:

```
.. important::

    This document is being prepared to replace 
Documentation/admin-guide/reporting-bugs.rst. The main work is done and 
you are already free to follow its instructions when reporting issues to 
the Linux kernel developers. But keep in mind, below text still needs a 
few finishing touches and review. It was merged to the Linux kernel 
sources at this stage to make this process easier and increase the 
text's visibility.

    Any improvements for the text or other feedback is thus very much 
welcome. Please send it to 'Thorsten Leemhuis <linux@leemhuis.info>' and 
'Jonathan Corbet <corbet@lwn.net>', ideally with 'Linux kernel mailing 
list (LKML) <linux-kernel@vger.kernel.org>' and the 'Linux Kernel 
Documentation List <linux-doc@vger.kernel.org>' in CC.

    Areas in the text that still need work or discussion contain a hint 
like this which point out the remaining issues; all of them start with 
the word "FIXME" to make them easy to find.
```

Randy let me know if you want to be mentioned there, too.

>   - In a separate patch you could add a comment to the existing document
>     pointing to the new one as the true source of wisdom.

This is what I plan to add:

```
.. note::

    Instead of reading below text consider reading this document 
instead: Documentation/admin-guide/reporting-issues.rst. It's intended 
to replace below text in the near future, as it's easier to grasp and 
more straight forward; it also provides way more details and more 
accurately describes the steps currently needed when reporting bugs to 
the Linux developers.
```

Ciao, Thorsten

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

[Randy Dunlap]

On 11/20/20 2:46 AM, Thorsten Leemhuis wrote:
>    Any improvements for the text or other feedback is thus very much welcome. Please send it to 'Thorsten Leemhuis <linux@leemhuis.info>' and 'Jonathan Corbet <corbet@lwn.net>', ideally with 'Linux kernel mailing list (LKML) <linux-kernel@vger.kernel.org>' and the 'Linux Kernel Documentation List <linux-doc@vger.kernel.org>' in CC.
> 
>    Areas in the text that still need work or discussion contain a hint like this which point out the remaining issues; all of them start with the word "FIXME" to make them easy to find.
> ```
> 
> Randy let me know if you want to be mentioned there, too.

No thanks, I don't need to be mentioned.
I'll see it (unless I can't).

-- 
~Randy

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

[Jonathan Corbet]

On Fri, 20 Nov 2020 11:46:07 +0100
Thorsten Leemhuis <linux@leemhuis.info> wrote:

> Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
> > On Sun, 15 Nov 2020 11:13:52 +0100
> > Thorsten Leemhuis <linux@leemhuis.info> wrote:  
> 
> >   - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
> >     (or some suitable name).  I do wonder if it should also move to the
> >     process manual as part of this; not only admins will report bugs.  
> 
> After a night's sleep and Randy's comment I for now settled on
> Documentation/admin-guide/reporting-issues.rst

Keeping it in the admin guide is OK.  Not sure about the name, though; if
you're really dead set against bugs, maybe reporting-problems.rst?

> >   - Add a comment at the top saying it's a proposed replacement and
> >     soliciting comments.  [...]  
> Struggled a bit to find the right words, but I think this should work:
> 
> ```
> .. important::
> 
>     This document is being prepared to replace 
> Documentation/admin-guide/reporting-bugs.rst. The main work is done and 
> you are already free to follow its instructions when reporting issues to 
> the Linux kernel developers. But keep in mind, below text still needs a 
> few finishing touches and review. It was merged to the Linux kernel 
> sources at this stage to make this process easier and increase the 
> text's visibility.
> 
>     Any improvements for the text or other feedback is thus very much 
> welcome. Please send it to 'Thorsten Leemhuis <linux@leemhuis.info>' and 
> 'Jonathan Corbet <corbet@lwn.net>', ideally with 'Linux kernel mailing 
> list (LKML) <linux-kernel@vger.kernel.org>' and the 'Linux Kernel 
> Documentation List <linux-doc@vger.kernel.org>' in CC.
> 
>     Areas in the text that still need work or discussion contain a hint 
> like this which point out the remaining issues; all of them start with 
> the word "FIXME" to make them easy to find.
> ```

Seems OK.

> >   - In a separate patch you could add a comment to the existing document
> >     pointing to the new one as the true source of wisdom.  
> 
> This is what I plan to add:
> 
> ```
> .. note::
> 
>     Instead of reading below text consider reading this document 
> instead: Documentation/admin-guide/reporting-issues.rst. It's intended 
> to replace below text in the near future, as it's easier to grasp and 
> more straight forward; it also provides way more details and more 
> accurately describes the steps currently needed when reporting bugs to 
> the Linux developers.
> ```

I'd be a bit more straightforward:

	This document is obsolete, and will be replaced by
	Documentation/admin-guide/$NAME in the near future.

Not sure that more is really needed?

jon

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

[Jonathan Corbet]

On Thu, 19 Nov 2020 13:29:51 +0100
Thorsten Leemhuis <linux@leemhuis.info> wrote:

> >   - Dual licensed CC-SA-4.0 is fine with me.  CC-BY is OK if you really
> >     want to do it that way.    
> 
> I'm unsure and would appreciate options from others here.
> 
> Here are some of my thoughts about this:
> 
> What do we loose by dual-licensing it under a liberal license like 
> CC-BY? It afaics makes it a lot more attractive for websites or books 
> authors to use this text as a base, as they don't need to fear that 
> "share alike" or the GPL might have consequences on the surroundings. 
> I'd say that's a good thing for the kernel, as it increases the chances 
> the texts built upon ours remain close to what we expect on this topic.
> 
> That's why I currently think using CC-BY is a good idea.

It's a matter of preferences; I like -SA better as a closer match to the
kernel's GPL licensing.  But it's your text, so it's your choice.

jon

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

[Thorsten Leemhuis]

Am 20.11.20 um 22:58 schrieb Jonathan Corbet:
> On Fri, 20 Nov 2020 11:46:07 +0100
> Thorsten Leemhuis <linux@leemhuis.info> wrote:
>> Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
>>> On Sun, 15 Nov 2020 11:13:52 +0100
>>> Thorsten Leemhuis <linux@leemhuis.info> wrote:
>>
>>>    - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
>>>      (or some suitable name).  I do wonder if it should also move to the
>>>      process manual as part of this; not only admins will report bugs.
>> After a night's sleep and Randy's comment I for now settled on
>> Documentation/admin-guide/reporting-issues.rst
> Keeping it in the admin guide is OK.  Not sure about the name, though; if
> you're really dead set against bugs, maybe reporting-problems.rst?

Well, I'm not dead set against bugs, but it somehow seems wrong to me: 
people have problems/issues they deal with, which in the end might turn 
out to not be a bug/error in the code at all. That afaics why tracker 
software for such reports is often called "issue tracker" instead of 
"bug tracker" (and nearly nobody calls them problem trackers afaics).. 
That's why I went with "issues" in the name and the text.

But in the end I'm not a native English speaker, so I guess it's better 
if I follow advice from those. Randy, what would you choose?

> I'd be a bit more straightforward:
> 
> 	This document is obsolete, and will be replaced by
> 	Documentation/admin-guide/$NAME in the near future.
> 
> Not sure that more is really needed?

Totally fine for me (I guess I tried to be less bold and was overly 
careful).

@Jonathan, one more question: when I submit this again, should I CC more 
people (Linus, Greg, ?) to give them a chance to speak up before this 
lands in your tree?

Ciao, Thorsten

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

[Randy Dunlap]

On 11/21/20 9:33 PM, Thorsten Leemhuis wrote:
> Am 20.11.20 um 22:58 schrieb Jonathan Corbet:
>> On Fri, 20 Nov 2020 11:46:07 +0100
>> Thorsten Leemhuis <linux@leemhuis.info> wrote:
>>> Am 19.11.20 um 01:29 schrieb Jonathan Corbet:
>>>> On Sun, 15 Nov 2020 11:13:52 +0100
>>>> Thorsten Leemhuis <linux@leemhuis.info> wrote:
>>>
>>>>    - Collapse the whole thing down to a patch adding reporting-bugs-v2.rst
>>>>      (or some suitable name).  I do wonder if it should also move to the
>>>>      process manual as part of this; not only admins will report bugs.
>>> After a night's sleep and Randy's comment I for now settled on
>>> Documentation/admin-guide/reporting-issues.rst
>> Keeping it in the admin guide is OK.  Not sure about the name, though; if
>> you're really dead set against bugs, maybe reporting-problems.rst?
> 
> Well, I'm not dead set against bugs, but it somehow seems wrong to me: people have problems/issues they deal with, which in the end might turn out to not be a bug/error in the code at all. That afaics why tracker software for such reports is often called "issue tracker" instead of "bug tracker" (and nearly nobody calls them problem trackers afaics).. That's why I went with "issues" in the name and the text.
> 
> But in the end I'm not a native English speaker, so I guess it's better if I follow advice from those. Randy, what would you choose?

I'm fine with "issues."

I do recall that at my first job (that was in the previous century or
previous millennium) they were called "trouble reports."  :)

-- 
~Randy