Bug#627960: [PATCH 3/3] Add a quick tutorial about bisecting
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
This doesn't address the "why do version numbers jump around while
bisecting?" question[1]. Not sure how to address it briefly;
hopefully this is a good enough start without it.
That's the end of the series. Thanks for reading.
[1] https://git.wiki.kernel.org/index.php/GitFaq#Why_does_.22git_bisect.22_make_me_test_versions_outside_the_.22good-bad.22_range.3F
chapter-common-tasks.sgml | 80 +++++++++++++++++++++++++++++++++++++++++++++
debian/changelog | 5 +++
2 files changed, 85 insertions(+), 0 deletions(-)
diff --git a/chapter-common-tasks.sgml b/chapter-common-tasks.sgml
index dc482d7..a4ccc50 100644
--- a/chapter-common-tasks.sgml
+++ b/chapter-common-tasks.sgml
@@ -402,6 +402,86 @@ $ cp /boot/config-2.6.18-3-686 ./.config
may be started using <tt>make deb-pkg</tt> target as described above.
</sect>
+ <sect id="common-bisecting">
+ <heading>Bisecting (finding the upstream version that introduced a bug)</heading>
+ <p>
+ When a bug is easy to reproduce locally but hard to get developers
+ to reproduce (as is often true of workflow- or hardware-dependent
+ bugs), it can be useful to compile and test a few versions to narrow
+ down what changes introduced the regression.
+ </p>
+
+ <p>
+ To start, recreate the problem with a vanilla kernel:
+ <example>
+# apt-get install git build-essential
+$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
+$ cd linux-2.6
+$ make localmodconfig; # minimal configuration
+ </example>
+ The above commands acquire and configure a vanilla kernel.
+ Build and test a binary package as explained in
+ <ref id="common-building">:
+ <example>
+$ make deb-pkg
+$ cd ..
+# dpkg -i *.deb
+# reboot
+ </example>
+ If the bug doesn't show up, try again with the standard
+ configuration file from /boot. (If it still doesn't show up
+ after that, declare victory and celebrate.)
+ </p>
+
+ <p>
+ Initialize the bisection process by declaring which versions worked
+ and did not work:
+ <example>
+$ cd linux-2.6
+$ git bisect start
+$ git bisect bad; # current version is bad
+$ git bisect good v2.6.12; # or whichever was known to be good
+ </example>
+ Now git checks out a version half-way in between to test.
+ Build it, reusing the prepared configuration.
+ <example>
+$ make silentoldconfig
+$ make deb-pkg
+ </example>
+ </p>
+
+ <p>
+ Install the package, reboot, and test.
+ <example>
+$ git bisect good; # if this version doesn't exhibit the bug
+$ git bisect bad; # if it does
+$ git bisect skip; # if some other bug makes it hard to test
+ </example>
+ And on to the next iteration:
+ <example>
+$ make silentoldconfig
+$ make deb-pkg
+ </example>
+ </p>
+
+ <p>
+ At the end of the process, the name of the "first bad commit" is
+ printed, which is very useful for tracking down the bug. Narrowing
+ down the regression range with a few rounds is useful even if you
+ don't get that far; in that case, run <tt>git bisect log</tt> to
+ produce a log. If you are the visual sort of person, <tt>git bisect
+ visualize</tt> with the <tt>gitk</tt> package installed can show
+ what is happening between steps.
+ </p>
+
+ <p>
+ See Christian Couder's article "Fighting regressions with git bisect"
+ from <url id="http://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html";
+ name="kernel.org"> or <url id="file:///usr/share/doc/git/html/git-bisect-lk2009.html"
+ name="the git-doc package"> for details.
+ </p>
+ </sect>
+
<sect id="common-out-of-tree">
<heading>Building out-of-tree kernel modules</heading>
<p>
diff --git a/debian/changelog b/debian/changelog
index 4470a15..0028bf6 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,8 +1,13 @@
kernel-handbook (1.0.11) UNRELEASED; urgency=low
+ [ Ben Hutchings ]
* Remove description of yaird and comparison with initramfs-tools
* Mention dracut as an experimental initramfs generator
+ [ Jonathan Nieder ]
+ * Explain in the "common kernel-related tasks" chapter how to
+ pinpoint regressions with "git bisect" - closes: #627960
+
-- Ben Hutchings <ben@decadent.org.uk> Tue, 17 May 2011 03:58:04 +0100
kernel-handbook (1.0.10) unstable; urgency=low
--
1.7.5.1
Reply to: