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 <[email protected]> CC: [email protected] 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
