Rewrite the section that explains why a fresh kernel is needed and why
bug reporters might have to compile one themselves for testing and
debugging purposes.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
.../admin-guide/reporting-issues.rst | 141 +++++++++++-------
1 file changed, 85 insertions(+), 56 deletions(-)
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index 7dfb3ca4b3e322..2f387e8766f21d 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -49,11 +49,25 @@ Step-by-step guide on reporting Linux kernel issues
Note: Only the steps starting with '*you must*' are strictly required -- but
following the others is usually in your own interest.
- * Are you facing an issue with a Linux kernel a hardware or software vendor
- provided? Then in almost all cases you are better off to stop reading this
- document and reporting the issue to your vendor instead, unless you are
- willing to install the latest Linux version yourself. Be aware the latter
- will often be needed anyway to hunt down and fix issues.
+.. _intro_repisbs:
+
+* Be aware:
+
+ * You should report issues using a Linux kernel that is both really fresh and
+ vanilla. That often means that you will have to remove software that
+ requires externally developed kernel modules and install the newest upstream
+ Linux development kernel yourself.
+
+ * There is a decent chance you will have to report the problem by email, in
+ which case your email address will become part of public archives.
+
+ * You might need to patch and build your own kernel to help developers debug
+ and fix the bug.
+
+ If these three aspects sound too demanding, consider reporting the issue to
+ your Linux distributor or hardware manufacturer instead.
+
+ [:ref:`details <intro_repiref>`]
* Perform a rough search for existing reports with your favorite internet
search engine; additionally, check the archives of the `Linux Kernel Mailing
@@ -265,57 +279,72 @@ With that off the table, find below details for the steps from the detailed
guide on reporting issues to the Linux kernel developers.
-Make sure you're using the upstream Linux kernel
-------------------------------------------------
-
- *Are you facing an issue with a Linux kernel a hardware or software vendor
- provided? Then in almost all cases you are better off to stop reading this
- document and reporting the issue to your vendor instead, unless you are
- willing to install the latest Linux version yourself. Be aware the latter
- will often be needed anyway to hunt down and fix issues.*
-
-Like most programmers, Linux kernel developers don't like to spend time dealing
-with reports for issues that don't even happen with their current code. It's
-just a waste everybody's time, especially yours. Unfortunately such situations
-easily happen when it comes to the kernel and often leads to frustration on both
-sides. That's because almost all Linux-based kernels pre-installed on devices
-(Computers, Laptops, Smartphones, Routers, …) and most shipped by Linux
-distributors are quite distant from the official Linux kernel as distributed by
-kernel.org: these kernels from these vendors are often ancient from the point of
-Linux development or heavily modified, often both.
-
-Most of these vendor kernels are quite unsuitable for reporting issues to the
-Linux kernel developers: an issue you face with one of them might have been
-fixed by the Linux kernel developers months or years ago already; additionally,
-the modifications and enhancements by the vendor might be causing the issue you
-face, even if they look small or totally unrelated. That's why you should report
-issues with these kernels to the vendor. Its developers should look into the
-report and, in case it turns out to be an upstream issue, fix it directly
-upstream or forward the report there. In practice that often does not work out
-or might not what you want. You thus might want to consider circumventing the
-vendor by installing the very latest Linux kernel core yourself. If that's an
-option for you move ahead in this process, as a later step in this guide will
-explain how to do that once it rules out other potential causes for your issue.
-
-Note, the previous paragraph is starting with the word 'most', as sometimes
-developers in fact are willing to handle reports about issues occurring with
-vendor kernels. If they do in the end highly depends on the developers and the
-issue in question. Your chances are quite good if the distributor applied only
-small modifications to a kernel based on a recent Linux version; that for
-example often holds true for the mainline kernels shipped by Debian GNU/Linux
-Sid or Fedora Rawhide. Some developers will also accept reports about issues
-with kernels from distributions shipping the latest stable kernel, as long as
-it's only slightly modified; that for example is often the case for Arch Linux,
-regular Fedora releases, and openSUSE Tumbleweed. But keep in mind, you better
-want to use a mainline Linux and avoid using a stable kernel for this
-process, as outlined in the section 'Install a fresh kernel for testing' in more
-detail.
-
-Obviously you are free to ignore all this advice and report problems with an old
-or heavily modified vendor kernel to the upstream Linux developers. But note,
-those often get rejected or ignored, so consider yourself warned. But it's still
-better than not reporting the issue at all: sometimes such reports directly or
-indirectly will help to get the issue fixed over time.
+.. _intro_repiref:
+
+You likely need to compile at least one really fresh kernel
+-----------------------------------------------------------
+
+ *Be aware:You should report issues using a Linux kernel that is both really
+ fresh and vanilla. [...] Your email address will become part of public
+ archives [...] You might need to patch and build your own kernel* [:ref:`... <intro_repisbs>`]
+
+You most likely will have to fiddle with your setup and install at least one
+fresh Linux kernel while reporting the issue or trying to resolve it. The
+step-by-step guide mentions a few, but the most important is:
+
+The kernels most Linux users utilize are unsuitable for reporting bugs
+upstream, as the problem might have been fixed already or never happened with
+the upstream code in the first place. Such situations occur frequently when it
+comes to Linux:
+
+1. Many developers consider all 'longterm' (aka 'LTS') kernels as too old and
+ thus unsuitable for reporting, except for series-specific regressions (say
+ from 6.1.13 to 6.1.15) in still-supported series (see `frontpage of
+ kernel.org <https://kernel.org/>`_). Reporting using the newest version from
+ the latest 'stable' series can work -- but some developers only take a
+ closer look at bugs reported using a fresh mainline kernel, as the bug might
+ have been fixed already.
+
+2. Almost all Linux-based kernels pre-installed on devices (computers, laptops,
+ smartphones, routers, …) are therefore too old as well, but even when not,
+ often unsuitable for a second reason:
+
+ Most vendors modify Linux's source code (some heavily!) before building their
+ kernels; frequently their kernels also load externally developed modules
+ ('out-of-tree drivers'), too. Such modifications or enhancements might be
+ causing your issue, even when they seem tiny and unrelated. Upstream
+ developers can do nothing about such problems.
+
+ You therefore have to report issues with such kernels to the vendor. Its
+ developers should look into the report and, in case it turns out to be an
+ upstream issue, report or directly fix it there. In practice that often does
+ not work out or might not be what you want; installing your own fresh vanilla
+ kernel while steering clear of externally developed modules is your way out
+ here.
+
+Note: Some developers, despite the aforementioned aspects, are willing to handle
+reports about issues in kernels that are somewhat older or slightly diverged.
+If they will highly depends on the circumstances:
+
+* Your chances are quite good if the vendor performed only small changes to a
+ recent mainline codebase; that, for example, often holds true for the kernels
+ shipped by Debian GNU/Linux Sid (aka 'unstable') or Fedora Rawhide.
+
+* Chances are slightly worse but still relatively good for reports about issues
+ with the newest version from the latest Linux stable series. That is the case
+ even when the distributor slightly modified or enhanced the kernel's code --
+ this, for example, is often the case for the default kernels of Arch Linux and
+ openSUSE Tumbleweed, as well as regular Fedora releases when using the latest
+ stable series.
+
+You are free to ignore this advice and report problems to the upstream Linux
+developers occurring with kernels that are outdated, modified, or utilizing
+out-of-tree drivers. But be aware that developers might react coldly or never
+at all. Nevertheless, it is still better than not reporting the issue:
+sometimes such a report directly or indirectly helps to resolve issues over
+time.
+
+[:ref:`back to step-by-step guide <intro_repisbs>`]
Search for existing reports, first run
--
2.51.0