On 26.03.21 07:15, Thorsten Leemhuis wrote: > On 26.03.21 07:13, Thorsten Leemhuis wrote: >> >> Lo! Since a few months mainline in >> Documentation/admin-guide/reporting-issues.rst contains a text written >> to obsolete the good old reporting-bugs text. For now, the new document >> still contains a warning at the top that basically says "this is WIP". >> But I'd like to remove that warning and delete reporting-bugs.rst in the >> next merge window to make reporting-issues.rst fully official. With this >> mail I want to give everyone a chance to take a look at the text and >> speak up if you don't want me to move ahead for now. >> >> For easier review I'll post the text of reporting-issues.rst in reply to >> this mail. I'll do that in a few chunks, as if this was a cover letter >> for a patch-set. > Here we go: > [...] > Reporting issues > ++++++++++++++++ > > The short guide (aka TL;DR) > =========================== > > [...] FWIW, on another channel someone mentioned the process in the TLDR is quite complicated when it comes to regressions in stable and longterm kernels. I looked at the text and it seemed like a valid complaint, esp. as those regressions are something we really care about. To solve this properly I sadly had to shake up the text in this section completely and rewrite parts of it. Find the result below. I'm quite happy with it, as it afaics is more straight forward and easier to understand. And it matches the step-by-step guide better. And the best thing: it's a bit shorter than the old TLDR. I'll wait a day or two and then will send it through the regular review together with a few small other fixes that piled up for the text, just wanted to add it here for completeness. --- The short guide (aka TL;DR) =========================== 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 and the stable maintainers. 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. If you would like to see the issue also fixed in a still supported stable or longterm series, 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. --- Ciao, Thorsten
