linux-kernel - [PATCH v1 26/30] docs: reporting-issues: improve text on second search

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <91a969bd0db253f59f579ec3a080404029756d3b.1761481839.git.linux@leemhuis.info>
Date: Sun, 26 Oct 2025 13:42:17 +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 26/30] docs: reporting-issues: improve text on second search

Fine-tune the instructions about searching lore again while dropping the
text on optimizing the write-up how to reproduce the issue: this is left
to a later step now.

Signed-off-by: Thorsten Leemhuis <linux@...mhuis.info>
---
 .../admin-guide/reporting-issues.rst          | 38 ++++++++++---------
 1 file changed, 20 insertions(+), 18 deletions(-)

diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index a78060098c59f0..aad98ccb49add8 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -257,11 +257,17 @@ following the others is usually in your own interest.
 
  [:ref:`details <verify_repiref>`]
 
- * Optimize your notes: try to find and write the most straightforward way to
-   reproduce your issue. Make sure the end result has all the important
-   details, and at the same time is easy to read and understand for others
-   that hear about it for the first time. And if you learned something in this
-   process, consider searching again for existing reports about the issue.
+.. _checkloretwo_repisbs:
+
+* If you performed a bisection or learned anything new about the bug while
+  following this guide so far, search once more for earlier reports
+  and fixes. In the bisection case, you want to search
+  `lore <https://lore.kernel.org/all/>`_   for the culprit's mainline commit-id
+  abbreviated to seven characters immediately followed by an asterisk (e.g.,
+  '`1f2e3d4 <https://lore.kernel.org/all/?q=1f2e3d4*>`_'); if that does not
+  produce any valuable insights, search for the commit's title, too.
+
+ [:ref:`details <checkloretwo_repiref>`]
 
  * If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider
    decoding the kernel log to find the line of code that triggered the error.
@@ -988,23 +994,19 @@ more detailed instructions, follow Documentation/admin-guide/verify-bugs-and-bis
 [:ref:`back to step-by-step guide <verify_repisbs>`]
 
 
-Optimize description to reproduce issue
----------------------------------------
+.. _checkloretwo_repiref:
 
-    *Optimize your notes: try to find and write the most straightforward way to
-    reproduce your issue. Make sure the end result has all the important
-    details, and at the same time is easy to read and understand for others
-    that hear about it for the first time. And if you learned something in this
-    process, consider searching again for existing reports about the issue.*
+Search again
+------------
 
-An unnecessarily complex report will make it hard for others to understand your
-report. Thus try to find a reproducer that's straight forward to describe and
-thus easy to understand in written form. Include all important details, but at
-the same time try to keep it as short as possible.
+  *If you performed a bisection or learned anything new about the bug
+  while following this guide so far, search once more* [:ref:`... <checkloretwo_repisbs>`]
 
-In this in the previous steps you likely have learned a thing or two about the
+During the previous step you likely have learned a thing or two about the
 issue you face. Use this knowledge and search again for existing reports
-instead you can join.
+and potential fixes.
+
+[:ref:`back to step-by-step guide <checkloretwo_repisbs>`]
 
 
 Decode failure messages
-- 
2.51.0