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

What are the package requirements
   koji
   GitPython
   fedpkg
   hmaccalc
   pesign
   bc
   gcc
   hostname
   m4
   net-tools
   openssl-devel
   elfutils-libelf-devel

   At least 15G of free disk space.

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?

   * Install the he fedbisect rpm

   * fedbisect sync <path for working>

     - This will create a working directory where builds and partial work will
        happen. This must be able to store at least 15G of objects

   * fedbisect start <working path> <bad version> <good 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 start the bisect.

   * fedbisect build <name of subdir>

     - Builds the current tree in the sub directory. This may take a while and
     there may be some messages about failures. That's okay as long as it
     continues to run. In order to get a proper set of patches, the scripts
     have to try lots of different combinations of patches. When it's done
     building, there will be rpms in <name of subdir>/step-$num . There is
     only a single RPM for both kernel and all modules.


   * Once you are done testing you can run

   fedbisect good <name of subdir>

   or

   fedbisect bad <name of subdir>

   to mark the build appropriately and then run fedbisect build <subdir>
   again to build.

   Repeat this process until the script indicates it founds a problem
   (git bisect message of first bad commit)