view release on metacpan or  search on metacpan

lib/Test/Against/Commit.pm  view on Meta::CPAN

We will end up comparing data stored in these installations' respective
C<results/analysis/> subdirectories.

    /path-to-application/goto-fatal/23ae7f95ea/results/analysis/
    /path-to-application/goto-fatal/v5.43.3/results/analysis/

=head2 What Preparations Are Needed to Use This Library?

=over 4

=item * Platform

The user should select a machine/platform which is likely to be reasonably
stable over one Perl 5 annual development cycle.  We presume that the
platform's system administrator will be updating system libraries for security
and other reasons over time.  But it would be a hassle to run this software on
a machine scheduled for a complete major version update of its operating
system.

=item * Perl 5 Configuration

The user must decide on a Perl 5 configuration for a given I<project> and then
must refrain from changing configurations over the course of the project's
existence.  See item under L<Terminology> above.

=item * F<perl> Executable Installation Location

As noted above, this library leaves to the user the choice of a I<way to get
the Perl source code> and the decision of I<how to configure> an individual
F<perl> executable.  It also leaves to the user, with one caveat, the decision
of I<where> to install that executable on disk.  That caveat is that the
I<installation> should reside in a directory named F<testing> which in turn
sits underneath a directory which we'll refer to as the I<application
directory>.  The user will have to manually create the I<application
directory>, the I<project directory>, the I<installation directory> and the
I<testing directory> and then use the I<testing directory> as the value for
the I<-Dprefix> option in the invocation of F<Configure>.

In terms of the directory structure discussed above, that the user would
create a directory structure something like this:

    $ cd ~/tmp
    $ export TESTINGDIR=`pwd`/all-tad-projects/goto-fatal/23ae7f95ea/testing
    $ echo $TESTINGDIR
    .../tmp/all-tad-projects/goto-fatal/23ae7f95ea/testing
    $ mkdir -p $TESTINGDIR
    $ ls -l $TESTINGDIR
    total 0

    $ cd <git checkout of perl branch or decompressed release tarball>

The user would then invoke F<Configure> in a way something like this:

    $ sh ./Configure -des -Dusedevel -Dprefix=$TESTINGDIR \
        -Uversiononly -Dman1dir=none -Dman3dir=none
    $ make install

The user could then confirm installation with this:

    $ $TESTINGDIR/bin/perl -v | head -2 | tail -1
    This is perl 5, version 43, subversion 3 (v5.43.3 (v5.43.2-343-g5fdb3e501b)) built for x86_64-linux

Note that at this point we have not yet created the I<results directory> ...

    $ cd ~/tmp
    $ ls -l ./all-tad-projects/goto-fatal/23ae7f95ea/results
    ... No such file or directory

... but no worries; Test-Against-Commit methods will handle that.

=item * Selection of CPAN Libraries for Testing

B<This is the most important step in preparation to use this library.>

When you use this library, you are in effect saying:  I<Here is a list of CPAN
modules important enough to me that I don't want to see them begin to break in
the course of Perl's annual development cycle.  (If they do break, then the
Perl 5 Porters and the modules' authors/maintainers must address how to handle
the breakage.)  To keep track of the problem, I'm going to build F<perl> from
a starting point where those modules are working proprerly and assess their
installability at later points.>

Hence, once you decide to track a certain CPAN library, you should continue to
include it in your list of modules to be tracked for the balance of that year's
development cycle.  You can, it is true, B<add> additional modules to your
list part way through the development cycle.  You simply won't have the same
baseline data that you have for the modules you selected at the very
beginning.

Here are some approaches that come to mind:

=over 4

=item * CPAN river

The CPAN river is a concept developed by Neil Bowers and other participants in
the Perl Toolchain Gang and Perl QA Hackathons and Summits.  The concept
starts from the premise that CPAN libraries upon which many other CPAN
libraries depend are more important than those upon which few other libraries
depend.  That's a useful definition of importance even if it is far from strictly
true.  Modules "way upstream" feed modules and real-world code "farther
downstream."  Hence, if Perl 5's development branch changes in a way such that
"upstream" modules start to fail to configure, build, test and install
correctly, then we have a potentially serious problem.

=item * Organizational dependencies

Many organizations use technologies such as F<Carton> and F<cpanfile> to keep
track of their dependencies on CPAN libraries.  The lists compiled by such
applications could very easily be translated into a list of modules tested
once a month against a Perl development release.

=item * What repeatedly breaks

Certain CPAN libraries get broken relatively frequently.  While this can
happen because of sub-standard coding practices in those libraries, it more
often happens because these libraries, in order to do what they want to do,
reach down deep into the Perl 5 guts and use features of the Perl-to-C API.

=back