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 <[email protected]> --- .../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
