Message-ID: <10a565e4ebca5e03a2e7abb7ffe1893136471bf9.1722846343.git.linux@leemhuis.info>
Date: Mon,  5 Aug 2024 10:27:15 +0200
From: Thorsten Leemhuis <linux@...mhuis.info>
To: Jonathan Corbet <corbet@....net>
Cc: regressions@...ts.linux.dev,
	linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	Bagas Sanjaya <bagasdotme@...il.com>,
	Petr Tesařík <petr@...arici.cz>
Subject: [PATCH v1] docs: bug-bisect: rewrite to better match the other bisecting text

Rewrite the short document on bisecting kernel bugs. The new text
improves .config handling, brings a mention of 'git skip', and explains
what to do after the bisection finished -- including trying a revert to
verify the result. The rewrite at the same time removes the unrelated
and outdated section on 'Devices not appearing' and replaces some
sentences about bug reporting with a pointer to the document covering
that topic in detail.

This overall brings the approach close to the one in the recently added
text Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst.
As those two texts serve a similar purpose for different audiences,
mention that document in the head of this one and outline when the
other might be the better one to follow.

Signed-off-by: Thorsten Leemhuis <linux@...mhuis.info>
---
 Documentation/admin-guide/bug-bisect.rst | 205 +++++++++++++++--------
 MAINTAINERS                              |   1 +
 2 files changed, 135 insertions(+), 71 deletions(-)

diff --git a/Documentation/admin-guide/bug-bisect.rst b/Documentation/admin-guide/bug-bisect.rst
index 325c5d0ed34a0a..f4a9acab65d0f5 100644
--- a/Documentation/admin-guide/bug-bisect.rst
+++ b/Documentation/admin-guide/bug-bisect.rst
@@ -1,76 +1,139 @@
-Bisecting a bug
-+++++++++++++++
-
-Last updated: 28 October 2016
-
-Introduction
-============
-
-Always try the latest kernel from kernel.org and build from source. If you are
-not confident in doing that please report the bug to your distribution vendor
-instead of to a kernel developer.
-
-Finding bugs is not always easy. Have a go though. If you can't find it don't
-give up. Report as much as you have found to the relevant maintainer. See
-MAINTAINERS for who that is for the subsystem you have worked on.
-
-Before you submit a bug report read
-'Documentation/admin-guide/reporting-issues.rst'.
-
-Devices not appearing
-=====================
-
-Often this is caused by udev/systemd. Check that first before blaming it
-on the kernel.
-
-Finding patch that caused a bug
-===============================
-
-Using the provided tools with ``git`` makes finding bugs easy provided the bug
-is reproducible.
-
-Steps to do it:
-
-- build the Kernel from its git source
-- start bisect with [#f1]_::
+.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
+.. [see the bottom of this file for redistribution information]
 
-	$ git bisect start
-
-- mark the broken changeset with::
-
-	$ git bisect bad [commit]
-
-- mark a changeset where the code is known to work with::
-
-	$ git bisect good [commit]
-
-- rebuild the Kernel and test
-- interact with git bisect by using either::
-
-	$ git bisect good
-
-  or::
-
-	$ git bisect bad
-
-  depending if the bug happened on the changeset you're testing
-- After some interactions, git bisect will give you the changeset that
-  likely caused the bug.
-
-- For example, if you know that the current version is bad, and version
-  4.8 is good, you could do::
-
-           $ git bisect start
-           $ git bisect bad                 # Current version is bad
-           $ git bisect good v4.8
+===============
+Bisecting a bug
+===============
 
+This document describes how to find a change causing a kernel regression using
+``git bisect``.
 
-.. [#f1] You can, optionally, provide both good and bad arguments at git
-	 start with ``git bisect start [BAD] [GOOD]``
+The text focuses on the gist of the process. If you are new to bisecting the
+kernel, better follow Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
+instead: it depicts everything from start to finish while covering multiple
+aspects even kernel developers occasionally forget. This includes:
 
-For further references, please read:
+- Detecting situations where a bisections would be a waste of time, as nobody
+  would care about the result -- for example, because the problem is triggered
+  by a .config change, was already fixed, is caused by something your Linux
+  distributor changed, occurs in an abandoned version, or happens after the
+  kernel marked itself as 'tainted'.
+- Preparing the .config file using an appropriate kernel while enabling or
+  disabling debug symbols depending on the situation's needs -- while optionally
+  trimming the .config to tremendously reduce the build time per bisection step.
+- For regressions in stable or longterm kernels: checking mainline as well, as
+  the result determines to whom the regression must be reported to.
 
-- The man page for ``git-bisect``
-- `Fighting regressions with git bisect <https://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html>`_
-- `Fully automated bisecting with "git bisect run" <https://lwn.net/Articles/317154>`_
-- `Using Git bisect to figure out when brokenness was introduced <http://webchick.net/node/99>`_
+Neither document describes how to report a regression, as that is covered by
+Documentation/admin-guide/reporting-issues.rst.
+
+Finding the change causing a kernel issue using a bisection
+===========================================================
+
+*Note: the following process assumes you prepared everything for a bisection;
+this includes having a Git clone with the appropriate sources, installing the
+software required to build and install kernels, as well as a .config file stored
+in a safe place (the following example assumes '~/prepared_kernel_.config') to
+use as pristine base at each bisection step.*
+
+* Preparation: start the bisection and tell Git about the points in the history
+  you consider to be working and broken, which Git calls 'good' and 'bad'::
+
+    git bisect start
+    git bisect good v6.0
+    git bisect bad v6.1
+
+  Instead of Git tags like 'v6.0' and 'v6.1' you can specify commit-ids, too.
+
+1. Copy your prepared .config into the build directory and adjust it to the
+   needs of the codebase Git checked out for testing::
+
+     cp ~/prepared_kernel_.config .config
+     make olddefconfig
+
+2. Now build, install, and boot a kernel; if any of this fails for unrelated
+   reasons, run ``git bisect skip`` and go back to step 1.
+
+3. Check if the feature that regressed works in the kernel you just built.
+
+   If it does, execute::
+
+     git bisect good
+
+   If it does not, run::
+
+     git bisect bad
+
+   Be sure what you tell Git is correct, as getting this wrong just once will
+   send the rest of the bisection totally off course.
+
+   Go back to back to step 1, if Git after issuing one of those commands checks
+   out another bisection point while printing something like 'Bisecting:
+   675 revisions left to test after this (roughly 10 steps)'.
+
+   You finished the bisection and move to the next point below, if Git instead
+   prints something like 'cafecaca0c0dacafecaca0c0dacafecaca0c0da is the first
+   bad commit'; right afterwards it will show some details about the culprit
+   including its patch description. The latter can easily fill your terminal,
+   so you might need to scroll up to see the message mentioning the culprit's
+   commit-id; alternatively, run ``git bisect log`` to show the result.
+
+* Recommended complementary task: put the bisection log and the current
+  .config file aside for the bug report; furthermore tell Git to reset the
+  sources to the state before the bisection::
+
+     git bisect log > ~/bisection-log
+     cp .config ~/bisection-config-culprit
+     git bisect reset
+
+* Recommended optional task: try reverting the culprit on top of the latest
+  codebase; if successful, this will validate your bisection and enable
+  developers to resolve the regression through a revert.
+
+  To try this, update your clone and check out latest mainline. Then tell Git to
+  revert the change::
+
+     git revert --no-edit cafec0cacaca0
+
+  This might be impossible, for example when the bisection landed on a merge
+  commit. In that case, abandon the attempt. Do the same, if Git fails to revert
+  the culprit because later changes depend on it -- unless you bisected using a
+  stable or longterm kernel series, in which case you want to retry using the
+  latest code from that series.
+
+  If a revert succeeds, build and test another kernel to validate the result of
+  the bisection. Mention the outcome in your bug report.
+
+Additional reading material
+---------------------------
+
+* The `man page for 'git bisect' <https://git-scm.com/docs/git-bisect>`_ and
+  `fighting regressions with 'git bisect' <https://git-scm.com/docs/git-bisect-lk2009.html>`_
+  in the Git documentation.
+* `Working with git bisect <https://nathanchance.dev/posts/working-with-git-bisect/>`_
+  from kernel developer Nathan Chancellor.
+* `Using Git bisect to figure out when brokenness was introduced <http://webchick.net/node/99>`_.
+* `Fully automated bisecting with 'git bisect run' <https://lwn.net/Articles/317154>`_.
+
+..
+   end-of-content
+..
+   This document is maintained by Thorsten Leemhuis <linux@...mhuis.info>. If
+   you spot a typo or small mistake, feel free to let him know directly and
+   he'll fix it. You are free to do the same in a mostly informal way if you
+   want to contribute changes to the text -- but for copyright reasons please CC
+   linux-doc@...r.kernel.org and 'sign-off' your contribution as
+   Documentation/process/submitting-patches.rst explains in the section 'Sign
+   your work - the Developer's Certificate of Origin'.
+..
+   This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top
+   of the file. If you want to distribute this text under CC-BY-4.0 only,
+   please use 'The Linux kernel development community' for author attribution
+   and link this as source:
+   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/bug-bisect.rst
+
+..
+   Note: Only the content of this RST file as found in the Linux kernel sources
+   is available under CC-BY-4.0, as versions of this text that were processed
+   (for example by the kernel's build system) might contain content taken from
+   files which use a more restrictive license.
diff --git a/MAINTAINERS b/MAINTAINERS
index b34385f2e46d92..90c8681d4d311c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6719,6 +6719,7 @@ DOCUMENTATION REPORTING ISSUES
 M:	Thorsten Leemhuis <linux@...mhuis.info>
 L:	linux-doc@...r.kernel.org
 S:	Maintained
+F:	Documentation/admin-guide/bug-bisect.rst
 F:	Documentation/admin-guide/quickly-build-trimmed-linux.rst
 F:	Documentation/admin-guide/reporting-issues.rst
 F:	Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst

base-commit: 8663dd38a7ba5b2bfd2c7b4271e6e63bc0ef1e42
-- 
2.45.0

Powered by blists - more mailing lists