README.rst
fedbisect

- What is this?
fedbisect is a set of scripts for bisecting Fedora kernels
For a basic primer on git bisection, see
https://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html

- Who should be interested in this?
Have you updated your kernel and found that your favorite feature doesn't
work 100%? (Booting is a favorite feature of the author). Is your favorite
feature tied to some hardware that the maintainers may not have? These
scripts can help to get a more specific answer about what is broken.

- Why is this helpful?
When regressions occur, identifying what change introduced a problem is a
key part of fixing the problem. Fedora releases rpms which contain a single
kernel version. Generally, users can report "this worked in version X but
stopped working in verion Y". The number of changes that went in between
X and Y may make it difficult to identify what exactly caused the regression.
This is what these scripts are useful for: identifying which specific commit
in an RPM caused a breakage.

- git bisect already handles bisection. Why the extra layer of scripts?
The Fedora kernel maintainers try to match the upstream tree as closely as
possible. In practice, the fedora kernel tree caries a set of patches on
top of the vanilla kernel. These patches get rebased every release. This
means a fedora git tree looks like

A - Fedora commit
B - Feodra commit
C - Fedora commit
D - Upstream commit
E - Upstream commit
F - Upstream commit
G - Upstream commit
H - Upstream commit
I - Upstream commit
J - Upstream commit

If this tree is bisected, commits D through J won't have any fedora
enhancements. Typically, the upstream tree will boot but features may
be missing.

- What do these scripts do about this?
These scripts run git bisect but they apply the fedora patches on top at each
step. So in testing you might test

A - Fedora commit
B - Fedora commit
C - Fedora commit
G - Upstream commit
H - Upstream commit
I - Upstream commit
J - Upstream commit

as one commit and

A - Fedora commit
B - Feodra commit
C - Fedora commit
E - Upstream commit
F - Upstream commit
G - Upstream commit
H - Upstream commit
I - Upstream commit
J - Upstream commit

as another and

A - Fedora commit
B - Feodra commit
C - Fedora commit
I - Upstream commit
J - Upstream commit

as yet a third.

- I've got two candidates. How do I do a bisect?

* git clone <location of repo>
* ./setup-pkg-git.sh <name of subdir>
This will clone a kernel tree in <subdir> of the repo.
* cd <subdir>/fedora
* ./fedbisect.sh start <good version> <bad version>
Note when giving versions, give version numbers only e.g.

4.0.6-300.fc22 (correct)
4.0.6-300.fc22.x86_64 (incorrect)
kernel-4.0.6-300.fc22 (incorrect)
v4.0.6 (incorrect)

This will build and install a kernel locally (this requires sudo accesss, you
will be prompted for your password when installing). The kernel will be tagged
with -fedbisect-$stepnum for you to boot into and test whatever you need.
Depending on the results of your test, you can do

./fedbisect good

or

./fedbisect bad

to build and install the next step of the kernel. Continue doing this until the
script indicates it founds a problem (git bisect message of first bad commit)

- Limitations/quirks
-- Currently only builds for x86_64 kernel. Need to add proper support for other
   arches.
-- Just uses 'make install' to install the kernel. Ideally this would spit out
   an rpm for easier installation and managment.
-- Need to support the 'skip' option in git-bisect
-- Probably not handling special cases in git trees very well
-- This generates a separate kernel version for each bisect step. This was a
   deliberate choice for testing purposes, mostly as a setup to how rpm
   versioning may work. Keep a close eye on the size of your /boot partition!
   If you are testing a lot of tags you may need to delete old kernels from
   /boot.