Make reporting-bugs easier to grasp and yet more detailed

index 42481ea7b41d..4bbb9132782b 100644
@@ -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
 ==========
 

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

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

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

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

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

index be1bce8d43aa..434e1a890dfe 100644
@@ -245,6 +245,33 @@ With that of the table, find below the details on how to properly report issues
 to the Linux kernel developers.
 
 
+Make sure you're using the upstream Linux kernel
+------------------------------------------------
+
+   *Stop reading this document and report the problem to your vendor instead,
+   unless you are running a vanilla mainline kernel already or are willing to
+   install it.*
+
+Like most programmers, Linux kernel developers don't like to spend time dealing
+with reports for issues that don't even happen with the source code they
+maintain: it's just a waste everybody's time, yours included. That's why you
+later will have to test your issue with the latest 'vanilla kernel': a kernel
+that was build using the Linux sources taken straight from
+`kernel.org <https://kernel.org/>`_ and not modified or enhanced in any way.
+
+Almost all kernels used in devices (Computers, Laptops, Smartphones, Routers,
+…) and most kernels shipped by Linux distributors are ancient from the point of
+kernel development and heavily modified. They thus do not qualify for reporting
+an issue to the Linux kernel developers: the issue you face with such a kernel
+might be fixed already or caused by the changes or additions, even if they look
+small or totally unrelated. That's why issues with such kernels need to be
+reported to the vendor that distributed it. Its developers should look into the
+report and, in case it turns out to be an upstream issue, fix it directly
+upstream or report it there. If the company or project is uncooperative or if
+you want to circumvent it consider installing the mainline kernel yourself; just
+make sure it's the latest one (see below).
+
+
 .. ############################################################################
 .. Temporary marker added while this document is rewritten. Sections above
 .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.

@@ -262,12 +289,6 @@ Please see https://www.kernel.org/ for a list of supported kernels.  Any
 kernel marked with [EOL] is "end of life" and will not have any fixes
 backported to it.
 
-If you've found a bug on a kernel version that isn't listed on kernel.org,
-contact your Linux distribution or embedded vendor for support.
-Alternatively, you can attempt to run one of the supported stable or -rc
-kernels, and see if you can reproduce the bug on that.  It's preferable
-to reproduce the bug on the latest -rc kernel.
-
 
 How to report Linux kernel bugs
 ===============================

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

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

index abf804719890..2900f477f42f 100644
@@ -1,3 +1,5 @@
+.. _taintedkernels:
+
 Tainted kernels
 ---------------
 

index 61b6592ddf74..3e9923c9650e 100644
@@ -370,6 +370,127 @@ from being loaded by specifying ``foo.blacklist=1`` as kernel parameter (replace
 'foo' with the name of the module in question).
 
 
+Locate kernel area that causes the issue
+----------------------------------------
+
+    *Locate the driver or kernel subsystem that seems to be causing the issue.
+    Find out how and where its developers expect reports. Note: most of the time
+    this won't be bugzilla.kernel.org, as issues typically need to be sent by
+    mail to a maintainer and a public mailing list.*
+
+It's crucial to send your report to the right people, as the Linux kernel is big
+project and most of its developers are only familiar with a very small part of
+it. Quite a few developers only care for just one driver; some of them also look
+after the various infrastructure building blocks the driver is building upon,
+but sometimes other maintainers take care of those. These people talk with each
+other, but work mostly separately from each other. But most of them don't care
+about file systems or memory management, which yet other people take care of.
+
+Problem is: the Linux kernel lacks a central bug tracker that all maintainers
+use, so you have to find the right way and place to report issues yourself. One
+way to do that: look at the `MAINTAINERS file in the Linux kernel sources
+<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_,
+which lists the points of contact for the various parts of the kernel. The file
+contains a long text with sections that among others will mention who maintains
+the various parts of the kernel and the development mailing list for that code.
+
+How to decode the maintainers file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To illustrate how to use the file lets assume the Wi-Fi in your Laptop suddenly
+misbehaves after updating the kernel. In that case it's likely an issue in the
+Wi-Fi driver; it could also be some code it builds upon: the Wi-Fi subsystem,
+the TCP/IP stack, which are all part of the Network subsystem. But unless you
+suspect the culprit lies there stick to the driver. Thus run the command
+``lspci -k`` to tell which kernel driver manages a particular hardware::
+
+       [user@something ~]$ lspci -k
+       [...]
+       3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32)
+         Subsystem: Bigfoot Networks, Inc. Device 1535
+         Kernel driver in use: ath10k_pci
+         Kernel modules: ath10k_pci
+       [...]
+
+The line starting with 'Kernel modules:' tells us the hardware is driven by a
+module called ´´ath10k_pci´´. If you now search for 'ath10k' in the MAINTAINER
+file you will find something like this::
+
+       QUALCOMM ATHEROS ATH10K WIRELESS DRIVER
+       M:      Some Human <[email protected]>
+       L:      [email protected]
+       W:      http://wireless.kernel.org/en/users/Drivers/ath10k
+       T:      git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git
+       S:      Supported
+       F:      drivers/net/wireless/ath/ath10k/
+
+First look out for line starting with 'S:', to make sure the code is
+'Supported', 'Maintained', or at least has someone that provides 'Odd Fixes' if
+the person has a spare minute. If it states 'Obsolete' then you are using some
+outdated code and should switch to the newer approach the kernel offers. If it
+says 'Orphan' you are out of luck: nobody takes care of the code anymore, hence
+there is nobody to send a report to. You need to fix this yourself or look
+somewhere else to find someone that is willing to help.
+
+Now look for a line starting with 'B:', as that will tell you where to find a
+bug tracker to file your issue. The example does not have such a line; that
+is the case for most sections, as Linux kernel development is completely driven
+by mail and only a few developers use a bug tracker.
+
+Thus, if there is no 'B:' look for lines staring with 'M:'. Those mention the
+name and the email addresses for the maintainers of the particular code. Also
+look for one starting with 'L:', which tells you the public mailing list where
+the code is developed. Your report later needs to go by mail to those addresses.
+Don't omit the mailing list when sending your issue report by mail! Maintainers
+are busy people and might leave some work for other developers on the list.
+
+Additionally, for all issue report send by mail make sure to also CC the Linux
+Kernel Mailing List <[email protected]>, commonly known as LKML. That
+won't increase visibility, as almost no kernel developer reads that list anymore
+due to its high traffic. But it will ensure the report can be found with a
+search in the LKML archives.
+
+If your curious what the other letters stand for search the MAINTAINER file
+near the top for a section 'Descriptions of section entries and preferred
+order'.
+
+Finding the maintainers with the help of a script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For people that have the Linux sources at hand there is an even better way to
+find the proper place to report, as it contains a script that tries to find all
+people to contact. This script will need a path to the source code in question.
+For drivers if often can be found with a command like this::
+
+       $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!'
+       drivers/net/wireless/ath/ath10k/ath10k_pci
+
+Pass that part to the script::
+
+       $ ./scripts/get_maintainer.pl -f drivers/net/wireless/ath/ath10k*
+       Some Human <[email protected]> (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER)
+       Another S. Human <[email protected]> (odd fixer:NETWORKING DRIVERS)
+       [email protected] (open list:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER)
+       [email protected] (open list:NETWORKING DRIVERS (WIRELESS))
+       [email protected] (open list:NETWORKING DRIVERS)
+       [email protected] (open list)
+
+Don't sent the initial report to all of them, stick to the maintainer and the
+mailing list initially ('Some Human <[email protected]>' and
+'[email protected]'). But you might want to contact the others later
+in case the maintainer is not reacting appropriately, as outlined in a later
+section of this document.
+
+A note for developer and experts: in case you cloned the Linux sources with git
+you might want to add ``--git`` when calling ``get_maintainer.pl``. The script
+then will look at the git commit history to find which people recently worked
+on the code in question. That sometimes gives a better result, but sometimes
+sends people in a wrong direction. The latter for example happens with code
+that is changed rarely (like old or unmaintained drivers), as such code is
+sometimes modified during tree-wide cleanups by developers that do not care
+about the particular code at all. Hence, use this option with care.
+
+
 .. ############################################################################
 .. Temporary marker added while this document is rewritten. Sections above
 .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.

@@ -392,51 +513,6 @@ How to report Linux kernel bugs
 ===============================
 
 
-Identify the problematic subsystem
-----------------------------------
-
-Identifying which part of the Linux kernel might be causing your issue
-increases your chances of getting your bug fixed. Simply posting to the
-generic linux-kernel mailing list (LKML) may cause your bug report to be
-lost in the noise of a mailing list that gets 1000+ emails a day.
-
-Instead, try to figure out which kernel subsystem is causing the issue,
-and email that subsystem's maintainer and mailing list.  If the subsystem
-maintainer doesn't answer, then expand your scope to mailing lists like
-LKML.
-
-
-Identify who to notify
-----------------------
-
-Once you know the subsystem that is causing the issue, you should send a
-bug report.  Some maintainers prefer bugs to be reported via bugzilla
-(https://bugzilla.kernel.org), while others prefer that bugs be reported
-via the subsystem mailing list.
-
-To find out where to send an emailed bug report, find your subsystem or
-device driver in the MAINTAINERS file.  Search in the file for relevant
-entries, and send your bug report to the person(s) listed in the "M:"
-lines, making sure to Cc the mailing list(s) in the "L:" lines.  When the
-maintainer replies to you, make sure to 'Reply-all' in order to keep the
-public mailing list(s) in the email thread.
-
-If you know which driver is causing issues, you can pass one of the driver
-files to the get_maintainer.pl script::
-
-     perl scripts/get_maintainer.pl -f <filename>
-
-If it is a security bug, please copy the Security Contact listed in the
-MAINTAINERS file.  They can help coordinate bugfix and disclosure.  See
-:ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` for more information.
-
-If you can't figure out which subsystem caused the issue, you should file
-a bug in kernel.org bugzilla and send email to
[email protected], referencing the bugzilla URL.  (For more
-information on the linux-kernel mailing list see
-http://vger.kernel.org/lkml/).
-
-
 Tips for reporting bugs
 -----------------------
 

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

index 4828e8924136..05de4e0259cb 100644
@@ -549,6 +549,19 @@ See the section 'Duties after the report went out' for details how to get
 properly involved.
 
 
+Prepare for emergencies
+-----------------------
+
+    *Create a fresh backup and put system repair and restore tools at hand.*
+
+Reminder, you are dealing with computers, and they sometimes do unexpected
+things, especially if you fiddle with crucial parts like the kernel of its
+operating system. That's what you are about to do in this process. Thus, make
+sure to create a fresh backup; also ensure you have all tools at hand to repair
+or reinstall the operating system as well as everything you need to restore the
+backup.
+
+
 .. ############################################################################
 .. Temporary marker added while this document is rewritten. Sections above
 .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.

index 05de4e0259cb..d96b21512c03 100644
@@ -562,6 +562,27 @@ or reinstall the operating system as well as everything you need to restore the
 backup.
 
 
+Make sure your kernel doesn't get enhanced
+------------------------------------------
+
+    *Ensure your system does not enhance its kernels by building additional
+    kernel modules on-the-fly locally, which solutions like DKMS might be doing
+    without your knowledge.*
+
+Your kernel will stop being 'vanilla' as soon as it loads a kernel module not
+build from the sources used to compile the kernel image itself. That why you
+need to ensure your Linux kernel stays vanilla by removing or disabling
+mechanisms like akmods and DKMS: those might build additional kernel modules
+automatically, for example when your boot into a newly installed Linux kernel
+the first time. Reboot after removing them and any modules they installed.
+
+Note, you might not be aware that your system is using one of these solutions:
+they often get set up silently when you install Nvidias proprietary graphics
+driver, VirtualBox, or other Software that requires a some support from a module
+not part of the Linux kernel. Your package manager might thus force you to
+remove those, too.
+
+
 .. ############################################################################
 .. Temporary marker added while this document is rewritten. Sections above
 .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.

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

index 2292b79cf462..f99d92a05bca 100644
@@ -617,6 +617,32 @@ should minimize it:
    look like a regression.
 
 
+Document how to reproduce issue
+-------------------------------
+
+    *Write down coarsely how to reproduce the issue. If you deal with multiple
+    issue at once, create separate notes for each of them and make sure they
+    work independently on a freshly booted system. That's needed, as each issue
+    needs to get reported to the kernel developers separately, unless they are
+    strongly entangled.*
+
+If you deal with multiple issue at once, you'll have to report each of them
+separately, as they might be handled by different developers. Describing various
+issues in one report also makes it quite difficult for others to tear it apart.
+Hence, only combine issues in one report if they are strongly entangled.
+
+Additionally, during the reporting process you will have to test if the issue
+happens with other kernel versions. Therefore, it will make your work easier if
+you know exactly how to reproduce it quickly on a freshly booted system.
+
+Note: it's often fruitless to debug issues that only happened once, as they
+might be caused by a bit flip due to cosmic radiation. That's why you should try
+to rule that out by reproducing the issue before going further. Feed free to
+ignore this if you are experienced enough to tell a one-time error due to faulty
+hardware apart from a kernel issue that rarely happens and thus is hard to
+reproduce.
+
+
 .. ############################################################################
 .. Temporary marker added while this document is rewritten. Sections above
 .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.

@@ -639,15 +665,6 @@ How to report Linux kernel bugs
 ===============================
 
 
-Tips for reporting bugs
------------------------
-
-It's REALLY important to report bugs that seem unrelated as separate email
-threads or separate bugzilla entries.  If you report several unrelated
-bugs at once, it's difficult for maintainers to tease apart the relevant
-data.
-
-
 Gather information
 ------------------
 

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

index dee6d65aa95c..02f846f4a324 100644
@@ -731,6 +731,19 @@ using ``git`` straight from the `official development repository on kernel.org
 <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_.
 
 
+Check 'taint' flag
+------------------
+
+    *Ensure the kernel you just installed does not 'taint' itself when running.*
+
+As outlined above in more detail already: the kernel sets a 'taint' flag when
+something happens that can lead to follow-up errors that look totally unrelated.
+That's why you need to check if the kernel you just installed does not set this
+flag. And if it does, you in almost all the cases needs to eliminate the reason
+for it before you reporting issues that occur with it. See the section above for
+details how to do that.
+
+
 .. ############################################################################
 .. Temporary marker added while this document is rewritten. Sections above
 .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.

index 02f846f4a324..2a7d13562905 100644
@@ -744,6 +744,22 @@ for it before you reporting issues that occur with it. See the section above for
 details how to do that.
 
 
+Reproduce issue with the fresh kernel
+-------------------------------------
+
+    *Reproduce the issue with the kernel you just installed. If it doesn't show
+    up there, head over to the instructions for issues only happening with
+    stable and longterm kernels if you want to see it fixed there.*
+
+Check if the issue occurs with the Linux kernel you just installed. If it was
+fixed there already, consider sticking with this version line and canceling
+your plan to report the issue. But keep in mind that other users might be
+plagued by it, as long as it's not fixed in either stable and longterm version
+from kernel.org (and thus vendor kernels derived from those). If you prefer to
+use one of those and help their users, head over to the section "Details about
+reporting issues only occurring in older kernel version lines" below.
+
+
 .. ############################################################################
 .. Temporary marker added while this document is rewritten. Sections above
 .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.

index 2a7d13562905..c9a3491bf4db 100644
@@ -760,6 +760,26 @@ use one of those and help their users, head over to the section "Details about
 reporting issues only occurring in older kernel version lines" below.
 
 
+Optimize description to reproduce issue
+---------------------------------------
+
+    *Optimize your notes: try to find and write the most straightforward way
+    to reproduce your issue. Make sure the end result has all the important
+    details, and at the same time is easy to read and understand for others
+    that hear about it for the first time. And if you learned something in this
+    process, consider searching again for existing reports about the issue.*
+
+An unnecessarily complex report makes it quite hard for others to understand
+your report later, thus try to find a reproducer that's straight forward to
+describe and thus easy to understand in written form. Make it long enough and
+include all important details, but at the same time try to keep it as short
+as possible.
+
+In this in the previous steps you likely have learned a thing or two about the
+issue you face. Use this knowledge and search again for existing reports
+instead you can join.
+
+
 .. ############################################################################
 .. Temporary marker added while this document is rewritten. Sections above
 .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.

index c9a3491bf4db..e1219e56979f 100644
@@ -780,6 +780,18 @@ issue you face. Use this knowledge and search again for existing reports
 instead you can join.
 
 
+Decode failure messages
+-----------------------
+
+    *If the failure includes a stack dump, like an Oops does, consider decoding
+    it to find the offending line of code.*
+
+When the kernel detects an error, it will print a stack dump that allows to
+identify the exact line of code where the issue happens. But that information
+sometimes needs to get decoded to be readable, which is explained in
+admin-guide/bug-hunting.rst.
+
+
 .. ############################################################################
 .. Temporary marker added while this document is rewritten. Sections above
 .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.

@@ -811,9 +823,7 @@ step-by-step instructions for how a user can trigger the bug.
 
 If the failure includes an "OOPS:", take a picture of the screen, capture
 a netconsole trace, or type the message from your screen into the bug
-report.  Please read "Documentation/admin-guide/bug-hunting.rst" before posting your
-bug report. This explains what you should do with the "Oops" information
-to make it useful to the recipient.
+report.
 
 This is a suggested format for a bug report sent via email or bugzilla.
 Having a standardized bug report form makes it easier for you not to

index 59567da344e8..38d9dbe7177d 100644
@@ -1,3 +1,5 @@
+.. _bugbisect:
+
 Bisecting a bug
 +++++++++++++++
 

59 lines not on this page · raw message

index 71c49347c544..b06935cad880 100644
@@ -845,6 +845,204 @@ freshly to each newer kernel version you try. Afterwards run
 enabling any new feature, as those are allowed to cause regressions.
 
 
+Write and send the report
+-------------------------
+
+    *Start to compile the report by writing a detailed description about the
+    issue. Always mentions a few things: the latest kernel version you installed
+    for reproducing, the Linux Distribution used, and your notes how to
+    reproduce the issue. Ideally, make the kernels build configuration (.config)
+    and the output from ``dmesg`` available somewhere on the net and link to it.
+    Include or upload all other information that might be relevant, like the
+    output/screenshot of an Oops or the output from ``lspci``. Once you wrote
+    this main part insert a normal length paragraph on top of it outlining the
+    issue and the impact quickly. On top of this add one sentence that briefly
+    describes the problem and gets people to read on. Now give the thing a
+    descriptive title or subject that yet again is shorter. Then you're ready to
+    send or file the report like the MAINTAINERS file told you, unless you are
+    dealing with one of those 'issues of high priority': they need special care
+    which is explained in 'Special handling for high priority issues' below.*
+
+Now that you have prepared everything it's time to write your report. How to do
+that is partly explained by the two documents linked to in the preface above.
+
+This text will only mention a few of the essentials as well as things apecific
+to the Linux kernel. There is one thing that fits both categories: the most
+crucial parts of your report are the title/subject, the first sentence and the
+first paragraph. Developers often get quite a lot of mail and have to quickly
+decide if one is really worth reading. Developer sometimes take just a few
+seconds to skim a mail before deciding if it's worth a closer look. Thus: the
+better the top section of your report, the higher are the chances that someone
+will look into it and help you. And that why you should ignore them for now
+and write the detailed report first. ;-)
+
+Things each report should mention
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Describe in detail how your issue happens with the fresh vanilla kernel you
+installed. Try to include the step-by-step instructions you wrote and optimized
+earlier that descibe how you and ideally others can reproduce the issue; in
+those rare cases where that's impossible try to describe what you did to trigger
+it.
+
+Also include all the relevant information others might need to understand the
+issue and its environment. What's actually needed depends a lot on the issue,
+but there are some things you should include always:
+
+ * the output from ``cat /proc/version``, which contains the Linux kernel
+   version number and the compiler it was built with.
+
+ * the Linux distribution the machine is running (``hostnamectl | grep
+   "Operating System"``)
+
+ * the architecture of the CPU and the operating system (``uname -mi``)
+
+ * if you are dealing with a regression and performed a bisection, mention the
+   subject and the commit-id of the culprit.
+
+In a lot of cases it's also wise to make two more things available to those
+that read your report:
+
+ * the configuration used for building your Linux kernel (the '.config' file)
+
+ * the kernels messages that you get from ``dmesg``. Make sure it near the top
+   contains a line like 'Linux version 5.8-1 ([email protected]) (gcc (GCC)
+   10.2.1, GNU ld version 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020', as
+   otherwise messages from the first boot phase are already gone from the
+   buffer. In this case instead consider using ``journalctl -b 0 -k``;
+   alternatively you can also reboot, reproduce the issue and call ``dmesg``
+   right afterwards.
+
+This data files are big, that's why it's a bad idea to put them directly into
+your report. If you are filing the issue in a bug tracker then attach them to
+the ticket. If you report the issue by mail do not attach them, as that makes
+the mail too large; instead do one of these things:
+
+ * Upload the files somewhere public (your website, a public file paste
+   service, a ticket created just for this purpose on `bugzilla.kernel.org
+   <https://bugzilla.kernel.org/>`_, ...) and include a link to them in your
+   report. Ideally use something where the files stay available for years, as
+   they could be useful to someone many years from now; this for example can
+   happen if somebody else runs into the same issue or when a developer works on
+   some code that was changed to fix your issue.
+
+ * Put the files aside and mention you will send them later in individual
+   replies to your own mail. Just remember to actually do that once the report
+   went out. ;-)
+
+Things that might be wise to provide
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Depending on the issue you might need to add more files with background data.
+Here are a few suggestions what often is good to provide:
+
+ * If you are dealing with a 'warning', an 'OOPS' or a 'panic' from the kernel,
+   include it. If you can't copy' n'paste it try to capture a netconsole trace
+   or take a picture of the screen.
+
+ * If the issue might be related to your computer hardware mention what kind of
+   system you use. If you for example have problems with your graphics card
+   mention its manufacturer and the cards model. If it's a Laptop mention its
+   name, but try to make sure it's meaningful. 'Dell XPS 13' for example is
+   not, because it might be the one from 2012; that one might look a bit similar
+   to the one sold today, but apart from that the two have nothing in common.
+   Hence, in such cases add the exact model number, which for example are
+   '9380' or '7390' for XPS 13 models introduced during 2019. Names like
+   'Lenovo Thinkpad T590' are also somewhat ambiguous: there are variants of
+   this Laptop with and without a dedicated graphics chip, so try to find the
+   exact models name or specify the main components.
+
+ * Mention the Software in the environment that's relevant. If you have
+   problems with loading modules, you want to mention the versions of kmod,
+   systemd, and udev in use. If one of the DRM drivers misbehaves, you want to
+   state the versions of libdrm and Mesa; also specify your Wayland compositor
+   or the X-Server and its driver. If you have a filesystem issue, mention the
+   version of corresponding filesystem utilities (e2fsprogs, btrfs-progs,
+   xfsprogs, …).
+
+ * Gather additional information from the kernel that might be of interest. The
+   output from ``lspci -nn`` will for example help others to identify what
+   hardware you use. If you have a problem with hardware you even might want to
+   make the output from ``sudo lspci -vvv`` available, as that provides
+   insights how the components were configured. For some issues it might be
+   good to include the contents of files like ``/proc/cpuinfo``,
+   ``/proc/ioports``, ``/proc/iomem``, ``/proc/modules``, or
+   ``/proc/scsi/scsi``. Some subsystem also offer tools to collect relevant
+   information. One such tool is ``alsa-info.sh`` `which the audio/sound
+   subsystem developers provide <https://www.alsa-project.org/wiki/AlsaInfo>`_.
+
+That will give your some ideas what data might be wise to send, but you have to
+think yourself what might be helpful for others to know. Don't worry too much
+about forgetting something: developers will ask for additional details they
+need; but making everything important available from the start increases the
+chance someone will take a closer look.
+
+The important part: the head of your report
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that you have the detailed part of the report prepared let's get back to
+the most important section: the first few sentences. Thus go to the top, add
+something like 'The detailed description:' before the part you wrote and insert
+two newlines at the top. Now write one normal length paragraph that describes
+the issue roughly. Leave out all boring details and focus on the crucial parts
+readers need to know to understand what this is all about; if you think this
+bug affects a lot of users, mention this to get people interested.
+
+Once you did that insert two more lines at the top and write a one sentence
+summary that explains quickly what the report is about. After that you have to
+get even more abstract and write an even short subject/title for the report.
+
+Now that you have written this part take some time to optimize it, as it is the
+most important parts of your report: a lot of people will only read this before
+they decide if reading the rest is time well spend.
+
+Now send or file the report like the `MAINTAINERS file
+<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
+told you, unless it's one of those 'issues of high priority' outlined earlier:
+In that read the next subsection before sending the report.
+
+Special handling for high priority issues
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+High priority issues need special handling when sending the report:
+
+
+ * *Regression* If the issue is a regression add [REGRESSION] to the mails
+   subject or the title in the bug-tracker. If you did not perform a bisection
+   mention at least the latest mainline version you tested that worked fine (say
+   5.7) and the oldest where the issue occurs (say 5.8). If you did a successful
+   bisection mention the commit id and subject of the change that causes the
+   regression. Also make sure to add the author of that change to your report;
+   if you need to file your bug in a bug-tracker forward the report to him in a
+   private mail and mention where your filed it.
+
+ * *Severe bug*: make sure the subject or ticket title as well as the first para
+   makes the severeness obvious.
+
+ * *Security issues*: for these issues your will have to evaluate if a
+   short-term risk to other users would arise if details were publicly
+   disclosed. If that's not the case simply proceed with reporting the issue as
+   described. For issues that bear such a risk you will need to adjust the
+   reporting process slightly:
+
+   * If the MAINTAINERS file instructed you to report the issue by mail, do not
+     CC any public mailing lists.
+
+   * If you were supposed to file the issue in a bug tracker make sure to mark
+     the ticket as 'private' or 'security issue'. If the bug tracker does not
+     offer a way to keep reports private, forget about it and send your report
+     as a private mail to the maintainers instead.
+
+   In both cases make sure to inform those that the MAINTAINERS file lists in
+   the section 'security contact'. Ideally CCing them on the mail with the
+   report. If you filed it in a bug tracker forward the reports text, but on top
+   of it put a small note where you mention that you filed it with a link to the
+   ticket.
+
+   See :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` for more
+   information.
+
+
 .. ############################################################################
 .. Temporary marker added while this document is rewritten. Sections above
 .. are new and dual-licensed under GPLv2+ and CC-BY 4.0, those below are old.

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

81 lines not on this page · raw message

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

@@ -1064,48 +1244,6 @@ backported to it.
 How to report Linux kernel bugs
 ===============================
 
-
-Follow up
-=========
-
-Expectations for bug reporters
-------------------------------
-
-Linux kernel maintainers expect bug reporters to be able to follow up on
-bug reports.  That may include running new tests, applying patches,
-recompiling your kernel, and/or re-triggering your bug.  The most
-frustrating thing for maintainers is for someone to report a bug, and then
-never follow up on a request to try out a fix.
-
-That said, it's still useful for a kernel maintainer to know a bug exists
-on a supported kernel, even if you can't follow up with retests.  Follow
-up reports, such as replying to the email thread with "I tried the latest
-kernel and I can't reproduce my bug anymore" are also helpful, because
-maintainers have to assume silence means things are still broken.
-
-Expectations for kernel maintainers
------------------------------------
-
-Linux kernel maintainers are busy, overworked human beings.  Some times
-they may not be able to address your bug in a day, a week, or two weeks.
-If they don't answer your email, they may be on vacation, or at a Linux
-conference.  Check the conference schedule at https://LWN.net for more info:
-
-	https://lwn.net/Calendar/
-
-In general, kernel maintainers take 1 to 5 business days to respond to
-bugs.  The majority of kernel maintainers are employed to work on the
-kernel, and they may not work on the weekends.  Maintainers are scattered
-around the world, and they may not work in your time zone.  Unless you
-have a high priority bug, please wait at least a week after the first bug
-report before sending the maintainer a reminder email.
-
-The exceptions to this rule are regressions, kernel crashes, security holes,
-or userspace breakage caused by new kernel behavior.  Those bugs should be
-addressed by the maintainers ASAP.  If you suspect a maintainer is not
-responding to these types of bugs in a timely manner (especially during a
-merge window), escalate the bug to LKML and Linus Torvalds.
-
 Thank you!
 
 [Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]