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