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
---
.../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 `]
* 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
