Received-SPF: pass (google.com: domain of linux-kernel+bounces-118962-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:40f1:3f00::1 as permitted sender) client-ip=2604:1380:40f1:3f00::1;
From: Thorsten Leemhuis <linux@leemhuis.info>
To: Jonathan Corbet <corbet@lwn.net>
Cc: regressions@lists.linux.dev,
	linux-doc@vger.kernel.org,
	linux-kernel@vger.kernel.org,
	workflows@vger.kernel.org
Subject: [RFC PATCH v1 2/2] docs: reporting-issue: rework the TLDR
Date: Tue, 26 Mar 2024 13:21:29 +0100
Message-ID: <2f5a78745cbe0a99a4592612d6ffd57a17619fb4.1711455295.git.linux@leemhuis.info>
In-Reply-To: <cover.1711455295.git.linux@leemhuis.info>
References: <cover.1711455295.git.linux@leemhuis.info>
Precedence: bulk
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

Rework the TLDR (aka the short guide) for various reasons:

* People had to read it entirely and then act upon what they learned,
  which from feedback I got was apparently somewhat hard and confusing
  given everything we expect from bug reporters; this partly was because
  the first paragraph covered a special case (regression in
  stable/longterm kernel) and not the main aspect most people cared
  about when they came to the document.

  Use a step-by-step approach to avoid this.

* Make use of
  Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst

* The 'quickly report a stable regression to the stable team' approach
  hardly worked out: most of the time the regression was not known yet.
  Try a different approach using the regressions list.

* Reports about stable/longterm regressions most of the time were
  greeted with a brief reply along the lines of 'Is mainline affected as
  well?'; this is needed to determine who is responsible, so it might as
  well make the reporter check that before sending the report (which
  verify-bugs-and-bisect-regressions.rst already tells them to do, too).

Not-signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 .../admin-guide/reporting-issues.rst          | 104 +++++++++++-------
 1 file changed, 62 insertions(+), 42 deletions(-)

diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index e6083946c146e8..5f3c840ab94524 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -5,48 +5,68 @@ Reporting issues
 ++++++++++++++++
 
 
-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 (stable@vger.kernel.org) and CC the regressions list
-(regressions@lists.linux.dev); ideally also CC the maintainer and the mailing
-list for the subsystem in question.
-
-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.
-
-The issue was fixed there, but you would like to see it resolved in a still
-supported stable or longterm series as well? Then 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.
-
-If you are facing multiple issues with the Linux kernel at once, report each
-separately. While writing your report, include all information relevant to the
-issue, like the kernel and the distro used. In case of a regression, CC the
-regressions mailing list (regressions@lists.linux.dev) to your report. Also try
-to pin-point the culprit with a bisection; if you succeed, include its
-commit-id and CC everyone in the sign-off-by chain.
-
-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.
+Reporting issues
+++++++++++++++++
+
+The short guide on reporting Linux kernel issues (aka "the TL;DR")
+==================================================================
+
+Rule out something external causes your kernel to misbehave: skim the output of
+``journalctl -k``; make sure the kernel is not tainted; consider a glitch in the
+environment (hardware, firmware, initramfs, distribution, file system, ...).
+
+If you deal with multiple issues, process each separately.
+
+Search `lore <https://lore.kernel.org/all/>`_ for earlier reports and fixes.
+Then the wider internet. Consult :ref:`MAINTAINERS <maintainers>` to determine
+how bugs for the affected driver or subsystem must be submitted. This is usually
+by mail and rarely bugzilla.kernel.org; if the driver or subsystem uses an
+externally archived list or one of various bug trackers, search those as well.
+
+In case you deal with a regression still occurring in a less than two (ideally:
+one) weeks old kernel that is vanilla or close to it: send a brief email to
+regressions@lists.linux.dev asking if the regression is known; consider
+continuing this guide right afterwards, but definitely do so if you do not
+receive a positive reply within three days.
+
+Verify the bug and in case of a regression potentially bisect it as described in
+Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst; alternatively
+perform these tasks through different measures as outlined in more detailed
+step-by-step guide below.
+
+Were you unable to reproduce a bug with a mainline kernel you want to see fixed
+in a stable or longterm series? A bug that is not a regression? Then move over
+to 'Resolving non-regressions only occurring in stable or longterm kernels'.
+
+Compile a report with all important details. This always includes the
+distribution and kernel version used. Most of the time you also want to describe
+relevant aspects of your system and make the kernel's log messages available; do
+the same for everything else most likely relevant. In case of a regression, make
+that aspect obvious in the title; also specify the last working and first broken
+early in the body.
+
+Submit your report in the appropriate way, which depends on the outcome of the
+verification:
+
+* Are you facing a regression within a stable or longterm kernel series you were
+  unable to reproduce in a mainline kernel? Then report it by email to the
+  stable team while CCing the regressions list (e.g. To: Greg Kroah-Hartman
+  <gregkh@linuxfoundation.org>, Sasha Levin <sashal@kernel.org>;
+  CC: stable@vger.kernel.org, regressions@lists.linux.dev) and everyone in the
+  culprit's 'Signed-off-by' chain.
+
+* In all other cases, submit the report as specified in MAINTAINERS. In case of
+  a regression you have to report by mail, CC the regressions list
+  (regressions@lists.linux.dev); when you know the culprit, also CC everyone in
+  its 'Signed-off-by' chain. In case of a regression you have to file in a bug
+  tracker, write a short heads-up email with a link to the report to the list
+  once you have done so -- if the culprit is known, CC everyone that signed the
+  culprit off, too.
+
+Answer any questions in a timely manner and help where you can to resolve the
+issue. Retest with at least every first release candidate (-rc1) of a new
+mainline version and report your findings.
+
 
 The detailed step-by-step guide on reporting Linux kernel issues
 ================================================================
-- 
2.44.0