Signed-off-by: Jonathan Nieder <jrnie...@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 <b...@decadent.org.uk> Tue, 17 May 2011 03:58:04 +0100 kernel-handbook (1.0.10) unstable; urgency=low -- 1.7.5.1 -- To UNSUBSCRIBE, email to debian-kernel-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/20110525213851.GC6210@elie
