Message-ID: <cover.1761481839.git.linux@leemhuis.info>
Date: Sun, 26 Oct 2025 13:41:51 +0100
From: Thorsten Leemhuis <linux@...mhuis.info>
To: Jonathan Corbet <corbet@....net>
Cc: workflows@...r.kernel.org,
	linux-doc@...r.kernel.org,
	regressions@...ts.linux.dev,
	linux-kernel@...r.kernel.org
Subject: [PATCH v1 00/30] docs: reporting-issues: rework

Hi! This patch reworks various parts of our text on bug reporting. I
started working on it for six reasons:

* I noticed that even experienced Linux users had trouble with the TLDR
  text, despite it being already quite long.

* I noticed a few areas where people were struggling when reporting
  issues and saw potential for improving the situation somewhat by
  rearranging and fine-tuning the order and the description of the
  step-by-step guide a little.

* I wanted to add a simple to follow "is this regression maybe known
  already?" option to avoid unnecessary trouble for reporters.

* I wanted to improve the interaction with
  Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst,
  which has a few bits with roots in reporting-issues.rst, but covers
  verifying bugs and bisecting a lot better.

* I wanted to make it easier to jump to the reference section and back
  by adding internal links, similar to how we did it in
  Documentation/admin-guide/quickly-build-trimmed-linux.rst and
  Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst.

* I found the tone of the old text somewhat off-putting; I think I made
  it better in a lot of places, but I suspect I missed a few areas that
  needed treatment – and maybe did not go far enough in some others. So
  please let me know if you spot cases that are too dim, some external
  feedback really would help.

 I worked on-and-off on this for maybe two years and the problem is:
what started as fine tuning in various places piled up. That together
with the newly added links & anchors and some text movements makes the
patchset huge. When you ignore those two aspects and look at individual
patches using a word diff algorithm it looks a lot less scary, but it
remains big – and thus sadly puts some load on reviewers and
translators. Sorry. I think it's worth it and tried to split things up
to facilitate handling.

If you want to see how the resulting text looks like, check out:
https://www.leemhuis.info/files/misc/Reporting%20issues%20%e2%80%94%20The%20Linux%20Kernel%20documentation.html

Feel also free to fix any typos you spot
https://docs.google.com/document/d/1To4xVY8M6BDMBXEhEbaXuacZESdMzNFGECHk1a6nVPI/edit?usp=sharing,
I'll pick those up for the next version. You can also add notes with
suggestions there. But please do not add anything that might be covered
by copyright.

Ciao, Thorsten

To: Jonathan Corbet <corbet@....net>
CC: linux-doc@...r.kernel.org

Thorsten Leemhuis (30):
  docs: reporting-issues: mention text is best viewed rendered
  docs: reporting-issues: tweak the reference section intro
  docs: reporting-issues: add conclusion to the step-by-step guide
  docs: reporting-issues: add proper appendix
  docs: reporting-issues: outline why reporting is complicated
  docs: reporting-issues: replace TLDR guide with more of an into
  docs: reporting-issues: explain need for fresh vanilla kernel
  docs: reporting-issues: add step about processing issues separately
  docs: reporting-issues: tell users to check the kernel log
  docs: reporting-issues: move 'check tainted flag' upwards
  docs: reporting-issues: improve first tainted check
  docs: reporting-issues: move 'check environment' upwards
  docs: reporting-issues: improve environment check
  docs: reporting-issues: improve text about checking for existing
    issues
  docs: reporting-issues: improve text on classifying the bug
  docs: reporting-issues: add fast-track for regressions
  docs: reporting-issues: move text on 'check MAINTAINERS file' upwards
  docs: reporting-issues: improve text on looking up place to report
  docs: reporting-issues: move text on 'check other places' upwards
  docs: reporting-issues: improve text on check other places
  docs: reporting-issues: improve text on backup et. al
  docs: reporting-issues: move text on 'initial write-up' upwards
  docs: reporting-issues: improve text on initial write-up
  docs: reporting-issues: improve text on bug verification
  docs: reporting-issues: improve text on non-regressions in stable
  docs: reporting-issues: improve text on second search
  docs: reporting-issues: make collecting files a separate step
  docs: reporting-issues: separate steps for optimizing and submitting
    reports
  docs: reporting-issues: separate steps for follow-up tasks
  docs: reporting-issues: fix a few line breaks

 .../admin-guide/reporting-issues.rst          | 2958 ++++++++---------
 1 file changed, 1426 insertions(+), 1532 deletions(-)


base-commit: b14a05303f06d951c6ef7e23e5c8f3e3be21e17e
-- 
2.51.0

Powered by blists - more mailing lists