Bug#627960: [PATCH v2] Add a quick tutorial about bisecting
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Changes since v1:
- move to "bugs" chapter
- use tabs to indent to match the prevailing style in that file
- reword debian/changelog entry
- other fixes mentioned below
Ben Hutchings wrote:
> On Wed, 2011-05-25 at 16:38 -0500, Jonathan Nieder wrote:
> [...]
>> +# dpkg -i *.deb
>
> This last command is not generally a good idea!
True. Updated to use an explicit KDEB_PKGVERSION and base the
filename on that.
> s/standard/official/
Fixed.
>> +$ 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
> [...]
>
> You can specify the initial bad and good versions on the same command.
That's true (and what I do), but it might be hard to remember the
order on the command line and I don't want to assume the reader knows
what HEAD means in
git bisect start HEAD v2.6.12
I've left it alone for now.
> 'Common tasks' is a big chapter already, and I'm not sure that bisection
> is that common. This might be better placed in the 'bugs' chapter.
Very good idea. Thanks.
chapter-bugs.sgml | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++
debian/changelog | 5 +++
2 files changed, 85 insertions(+), 0 deletions(-)
diff --git a/chapter-bugs.sgml b/chapter-bugs.sgml
index 571bbaf..07157e9 100644
--- a/chapter-bugs.sgml
+++ b/chapter-bugs.sgml
@@ -397,6 +397,86 @@
</item>
</list>
</p>
+
+ <sect1>
+ Bisecting (finding the upstream version that introduced a bug)
+
+ <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 KDEB_PKGVERSION=bisecting.1.0 deb-pkg
+# dpkg -i ../linux-image-2.6.18_bisecting.1.0_i386.deb
+# reboot
+ </example>
+ If the bug doesn't show up, try again with the official
+ 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 good v2.6.12; # or whichever was known to be good
+$ git bisect bad; # current version is bad
+ </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-doc/git-bisect-lk2009.html"
+ name="the git-doc package"> for details.
+ </p>
+ </sect1>
</sect>
</chapt>
diff --git a/debian/changelog b/debian/changelog
index 761a51a..b5eabef 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,5 +1,6 @@
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
* Explain how to build a linux-headers-common package, thanks to
@@ -9,6 +10,10 @@ kernel-handbook (1.0.11) UNRELEASED; urgency=low
* Refer to git repository, replacing the old svn repository
(Closes: #627835)
+ [ Jonathan Nieder ]
+ * Explain how to narrow the regression window with "git bisect"
+ when filing bugs (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.3
Reply to: