README

NAME
    Devel::Git::MultiBisect - Study build and test output over a range of
    git commits

DESCRIPTION
    Given a Perl library or application kept in git for version control, it
    is often useful to be able to compare the output collected from running
    one or more test files over a range of git commits. If that range is
    sufficiently large, a test may fail in more than one way over that
    range.

    If that is the case, then simply asking, *"When did this file start to
    fail?"* -- a question which "git bisect" is designed to answer -- is
    insufficient. In order to identify more than one point of failure, we
    may need to (a) capture the test output for each commit; or, (b) capture
    the test output only at those commits where the output changed. The
    output of a run of a test file may change for a variety of reasons: test
    failures, segfaults, changes in the number or content of tests, etc.

    Devel::Git::MultiBisect provides methods to achieve that objective. Its
    child classes, Devel::Git::MultiBisect::AllCommits and
    Devel::Git::MultiBisect::Transitions, provide different flavors of that
    functionality for objectives (a) and (b), respectively. Please refer to
    their documentation for further discussion.

  What Is Multisection?
    In this library we introduce the term multisection as a short-hand for
    multiple bisection. Instead of hoping to identify a single commit within
    a range of commits that will, in effect, divide that range into
    *"before"* and *"after"* sub-ranges, we hope to identify multiple
    commits within that range where an application's behavior changed
    significantly.

  Multisection of Build-Time Failures
    Perl 5 has many different configuration options, some of which are used
    infrequently. Given a specific set of configuration options and a
    sufficiently large number of git commits and, it is possible that Perl
    would fail to build ("i.e.", a build-time failure in make) in more than
    one way over that range.

    If that is the case, then simply asking, *"When did Perl start failing
    to build with this set of configuration options?"* is insufficient. We
    may need to capture the build-time error output at those commits where
    the output changed. Devel::Git::MultiBisect::BuildTransitions provides
    methods to achieve that objective. Please refer to their documentation
    for further discussion.

PREREQUISITES
    Perl 5.14 or higher.

    CPAN module Devel::CheckBin needed for "perl Makefile.PL".

    CPAN module Capture::Tiny needed for testing only.

    git.

INSTALL
        perl Makefile.PL
        make
        make test
        make install

    This library has not yet been tested on Windows.

    Once installed, start reading the documentation by calling:

        perldoc Devel::Git::MultiBisect