[PATCH v1 13/30] docs: reporting-issues: improve environment check

[Thorsten Leemhuis <linux@leemhuis.info>]

Fine-tune the instructions regarding the environment check.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 .../admin-guide/reporting-issues.rst          | 74 ++++++++++++-------
 1 file changed, 46 insertions(+), 28 deletions(-)

diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index 861237aaf94126..439ec52f270167 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -92,9 +92,17 @@ following the others is usually in your own interest.
 
  [:ref:`details <taintone_repiref>`]
 
+.. _checkenv_repisbs:
+
+* Evaluate briefly if some glitch in your kernel's environment might make it
+  misbehave -- like a hardware defect, an updated system firmware, a
+  misconfigured BIOS, an overclocked component, a kernel parameter enabling
+  something unsupported, a broken initramfs, an inconsistent file system,
+  changes to the linux-firmware files, or some malfunction/misconfiguration in
+  your Linux distribution.
+
+ [:ref:`details <checkenv_repiref>`]
 
- * Make sure it's not the kernel's surroundings that are causing the issue
-   you face.
 
  * Perform a rough search for existing reports with your favorite internet
    search engine; additionally, check the archives of the `Linux Kernel Mailing
@@ -481,39 +489,49 @@ These are the most frequent reasons why the kernel set the flag:
 [:ref:`back to step-by-step guide <taintone_repisbs>`]
 
 
-Ensure a healthy environment
-----------------------------
+.. _checkenv_repiref:
+
+Ensure there is nothing wrong with the kernel's surroundings
+------------------------------------------------------------
+
+  *Evaluate briefly if some glitch in your kernel's environment might make it
+  misbehave -- like a* [:ref:`... <checkenv_repisbs>`]
+
+Problems that look like a kernel issue are sometimes caused by its
+surroundings. It is impossible to detect sometimes -- but it is wise to rule
+out a few common causes before wasting time on a meaningless bug report:
+
+* When dealing with a regression (e.g., something stopped working or works worse
+  after updating the kernel), make sure it is not something else that changed
+  in parallel. That could be something else you updated at the same time, like
+  the BIOS, the boot loader, Mesa, the linux-firmware package, or something
+  else close to the kernel; but it could also be some change you performed in
+  the BIOS setup or your Linux distribution's configuration.
+
+* Try to make sure the hardware is healthy, as problems with it can result in a
+  multitude of issues that look like kernel bugs.
 
-    *Make sure it's not the kernel's surroundings that are causing the issue
-    you face.*
+  Ideally try to rule out faulty RAM or a dying device causes the problem.
 
-Problems that look a lot like a kernel issue are sometimes caused by build or
-runtime environment. It's hard to rule out that problem completely, but you
-should minimize it:
+  Also ensure your computer components run within their design specifications;
+  that is especially important for the main processor, the RAM, and the
+  motherboard. Therefore, stop undervolting or overclocking when facing a
+  potential kernel issue.
 
- * Use proven tools when building your kernel, as bugs in the compiler or the
-   binutils can cause the resulting kernel to misbehave.
+* Temporarily remove any optional kernel parameters you use, as they might
+  enable unsupported or experimental features.
 
- * Ensure your computer components run within their design specifications;
-   that's especially important for the main processor, the main memory, and the
-   motherboard. Therefore, stop undervolting or overclocking when facing a
-   potential kernel issue.
+* In case of any problems related to booting, check if the initramfs was
+  generated correctly.
 
- * Try to make sure it's not faulty hardware that is causing your issue. Bad
-   main memory for example can result in a multitude of issues that will
-   manifest itself in problems looking like kernel issues.
+* When dealing with a file system issue, check the file
+  system in question with ``fsck``, as it might be damaged in a way that leads
+  to unexpected kernel behavior.
 
- * If you're dealing with a filesystem issue, you might want to check the file
-   system in question with ``fsck``, as it might be damaged in a way that leads
-   to unexpected kernel behavior.
+* Use proven tools when building your kernel, as bugs in the compiler or the
+  linker can cause the resulting kernel to misbehave.
 
- * When dealing with a regression, make sure it's not something else that
-   changed in parallel to updating the kernel. The problem for example might be
-   caused by other software that was updated at the same time. It can also
-   happen that a hardware component coincidentally just broke when you rebooted
-   into a new kernel for the first time. Updating the systems BIOS or changing
-   something in the BIOS Setup can also lead to problems that on look a lot
-   like a kernel regression.
+[:ref:`back to step-by-step guide <checkenv_repisbs>`]
 
 
 Search for existing reports, first run
-- 
2.51.0