diff options
author | Thorsten Leemhuis <linux@leemhuis.info> | 2021-03-30 16:13:06 +0200 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2021-03-31 21:46:33 +0200 |
commit | 4d2f46a8cdb135f4eb2e427d3165abcb028e7cbe (patch) | |
tree | 95fb3751e883c5b135285b18b6276a0a2e1a541d /Documentation/admin-guide/reporting-issues.rst | |
parent | MAINTAINERS: add entry for Documentation/admin-guide/reporting-issues.rst (diff) | |
download | linux-4d2f46a8cdb135f4eb2e427d3165abcb028e7cbe.tar.xz linux-4d2f46a8cdb135f4eb2e427d3165abcb028e7cbe.zip |
docs: reporting-issues.rst: reshuffle and improve TLDR
Make the TLDR a bit shorter while improving it at the same time by going
straight to the aspects readers are more interested it. The change makes
the process especially more straight-forward for people that hit a
regression in a stable or longterm kernel. Due to the changes the TLDR
now also matches the step by step guide better.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/762ccd7735315d2fdaa79612fccc1f474881118b.1617113469.git.linux@leemhuis.info
[ jc: fixed transposed _` as noted by Thorsten ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/admin-guide/reporting-issues.rst')
-rw-r--r-- | Documentation/admin-guide/reporting-issues.rst | 75 |
1 files changed, 35 insertions, 40 deletions
diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst index ca809a4be620..b3583b2337cb 100644 --- a/Documentation/admin-guide/reporting-issues.rst +++ b/Documentation/admin-guide/reporting-issues.rst @@ -17,46 +17,41 @@ Reporting issues The short guide (aka TL;DR) =========================== -If you're facing multiple issues with the Linux kernel at once, report each -separately to its developers. Try your best guess which kernel part might be -causing the issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its -developers expect to be told about issues. Note, it's rarely -`bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as in almost all cases -the report needs to be sent by email! - -Check the destination thoroughly for existing reports; also search the LKML -archives and the web. Join existing discussion if you find matches. If you -don't find any, install `the latest Linux mainline kernel -<https://kernel.org/>`_. Make sure it's vanilla, thus is not patched or using -add-on kernel modules. Also ensure the kernel is running in a healthy -environment and is not already tainted before the issue occurs. - -If you can reproduce your issue with the mainline kernel, send a report to the -destination you determined earlier. Make sure it includes all relevant -information, which in case of a regression should mention the change that's -causing it which can often can be found with a bisection. Also ensure the -report reaches all people that need to know about it, for example the security -team, the stable maintainers or the developers of the patch that causes a -regression. Once the report is out, answer any questions that might be raised -and help where you can. That includes keeping the ball rolling: every time a -new rc1 mainline kernel is released, check if the issue is still happening -there and attach a status update to your initial report. - -If you can not reproduce the issue with the mainline kernel, consider sticking -with it; if you'd like to use an older version line and want to see it fixed -there, first make sure it's still supported. Install its latest release as -vanilla kernel. If you cannot reproduce the issue there, try to find the commit -that fixed it in mainline or any discussion preceding it: those will often -mention if backporting is planed or considered too complex. If backporting was -not discussed, ask if it's in the cards. In case you don't find any commits or -a preceding discussion, see the Linux-stable mailing list archives for existing -reports, as it might be a regression specific to the version line. If it is, -report it like you would report a problem in mainline (including the -bisection). - -If you reached this point without a solution, ask for advice one the -subsystem's mailing list. - +Are you facing a regression with vanilla kernels from the same stable or +longterm series? One still supported? Then search the `LKML +<https://lore.kernel.org/lkml/>`_ and the `Linux stable mailing list +<https://lore.kernel.org/stable/>`_ archives for matching reports to join. If +you don't find any, install `the latest release from that series +<https://kernel.org/>`_. If it still shows the issue, report it to the stable +mailing list (stable@vger.kernel.org). + +In all other cases try your best guess which kernel part might be causing the +issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its developers +expect to be told about problems, which most of the time will be by email with a +mailing list in CC. Check the destination's archives for matching reports; +search the `LKML <https://lore.kernel.org/lkml/>`_ and the web, too. If you +don't find any to join, install `the latest mainline kernel +<https://kernel.org/>`_. If the issue is present there, send a report. + +The issue was fixed there, but you would like to see it resolved in a still +supported stable or longterm series as well? Then install its latest release. +If it shows the problem, search for the change that fixed it in mainline and +check if backporting is in the works or was discarded; if it's neither, ask +those who handled the change for it. + +**General remarks**: When installing and testing a kernel as outlined above, +ensure it's vanilla (IOW: not patched and not using add-on modules). Also make +sure it's built and running in a healthy environment and not already tainted +before the issue occurs. + +While writing your report, include all information relevant to the issue, like +the kernel and the distro used. In case of a regression try to include the +commit-id of the change causing it, which a bisection can find. If you're facing +multiple issues with the Linux kernel at once, report each separately. + +Once the report is out, answer any questions that come up and help where you +can. That includes keeping the ball rolling by occasionally retesting with newer +releases and sending a status update afterwards. Step-by-step guide how to report issues to the kernel maintainers ================================================================= |