# Generated by Pod::WikiDoc version 0.17

=pod

=head1 NAME

CPAN::Reporter - Provides Test::Reporter support for CPAN.pm

=head1 VERSION

This documentation describes version 0.44.

=head1 SYNOPSIS

From the CPAN shell:

  cpan> install CPAN::Reporter
  cpan> reload cpan
  cpan> o conf init test_report

=head1 DESCRIPTION

CPAN::Reporter is an add-on for the CPAN.pm module that uses
L<Test::Reporter> to send the results of module tests to the CPAN
Testers project.  Support for CPAN::Reporter is available in CPAN.pm 
as of version 1.88.

The goal of the CPAN Testers project (L<http://testers.cpan.org/>) is to
test as many CPAN packages as possible on as many platforms as
possible.  This provides valuable feedback to module authors and
potential users to identify bugs or platform compatibility issues and
improves the overall quality and value of CPAN.

One way individuals can contribute is to send test results for each module that
they test or install.  Installing CPAN::Reporter gives the option of
automatically generating and emailing test reports whenever tests are run via
CPAN.pm.

=head1 GETTING STARTED

The first step in using CPAN::Reporter is to install it using whatever
version of CPAN.pm is already installed.  CPAN.pm will be upgraded as
a dependency if necessary.

  cpan> install CPAN::Reporter

If CPAN.pm was upgraded, it needs to be reloaded.

  cpan> reload cpan

If upgrading from a very old version of CPAN.pm, users may be prompted to renew
their configuration settings, including the 'test_report' option to enable
CPAN::Reporter.  

If not prompted automatically, users should manually initialize CPAN::Reporter
support.  After enabling CPAN::Reporter, CPAN.pm will automatically continue
with interactive configuration of CPAN::Reporter options.  (Remember to 
commit the CPAN configuration changes.)

  cpan> o conf init test_report
  cpan> o conf commit

Once CPAN::Reporter is enabled and configured, test or install modules with
CPAN.pm as usual.  

For example, to force CPAN to repeat tests for CPAN::Reporter to see how it
works:

  cpan> force test CPAN::Reporter

=head1 UNDERSTANDING TEST GRADES

CPAN::Reporter will assign one of the following grades to the report:

=over

=item *

C<<< pass >>> -- all tests were successful  

=back

=over

=item *

C<<< fail >>> -- one or more tests failed, one or more test files died during
testing or no test output was seen

=back

=over

=item *

C<<< na >>> -- tests could not be run on this platform or one or more test files
died because of missing prerequisites

=back

=over

=item *

C<<< unknown >>> -- no test files could be found (either tE<sol>*.t or test.pl) or 
a result could not be determined from test output

=back

=over

=item *

C<<< default >>> -- this is not an actual grade reported to CPAN Testers, but it
is used in action prompt configuration options to indicate a fallback action

=back

In returning results to CPAN.pm, "pass" and "unknown" are considered successful
attempts to "make test" or "Build test" and will not prevent installation.
"fail" and "na" are considered to be failures and CPAN.pm will not install
unless forced.

=head1 CONFIG FILE OPTIONS

Default options for CPAN::Reporter are read from a configuration file 
C<<< .cpanreporter/config.ini >>> in the user's home directory (Unix and OS X)
or "My Documents" directory (Windows).

The configuration file is in "ini" format, with the option name and value
separated by an "=" sign

   email_from = "John Doe" <johndoe@nowhere.org>
   cc_author = no

Interactive configuration of email address, action prompts and mail server
options may be repeated at any time from the CPAN shell.  

  cpan> o conf init test_report

Interactive configuration will also include any additional, non-standard
options that have been added manually to the configuration file.

Available options are described in the following sections.

=head2 Email Address (required)

CPAN::Reporter requires users to provide an email address that will be used
in the "From" header of the email to cpan-testers@perl.org.

=over

=item *

C<<< email_from = <email address> >>> -- email address of the user sending the
test report; it should be a valid address format, e.g.:

=back

  user@domain
  John Doe <user@domain>
  "John Q. Public" <user@domain>

Because C<<< cpan-testers >>> uses a mailing list to collect test reports, it is
helpful if the email address provided is subscribed to the list.  Otherwise,
test reports will be held until manually reviewed and approved.  

Subscribing an account to the cpan-testers list is as easy as sending a blank
email to cpan-testers-subscribe@perl.org and replying to the confirmation
email.

=head2 Action Prompts

Several steps in the generation of a test report are optional.  Configuration
options control whether an action should be taken automatically or whether
CPAN::Reporter should prompt the user for the action to take.  The action
to take may be different for each report grade.

Valid actions, and their associated meaning, are as follows:

=over

=item *

C<<< yes >>> -- automatic yes

=item *

C<<< no >>> -- automatic no

=item *

C<<< ask/no >>> or just C<<< ask >>> -- ask each time, but default to no

=item *

C<<< ask/yes >>> -- ask each time, but default to yes

=back

For "ask" prompts, the default will be used if return is pressed immediately at
the prompt or if the C<<< PERL_MM_USE_DEFAULT >>> environment variable is set to a
true value.

Action prompt options take one or more space-separated "grade:action" pairs,
which are processed left to right.

  edit_report = fail:ask/yes pass:no

An action by itself is taken as a default to be used for any grade which does
not have a grade-specific action.  A default action may also be set by using
the word "default" in place of a grade.  

  edit_report = ask/no
  edit_report = default:ask/no

A grade by itself is taken to have the action "yes" for that grade.

  edit_report = default:no fail

Multiple grades may be specified together by separating them with a slash.

  edit_report = pass:no fail/na/unknown:ask/yes

The action prompt options are:

=over

=item *

C<<< cc_author = <grade:action> ... >>> -- should module authors should be sent a copy of 
the test report at their C<<< author@cpan.org >>> address? (default:yes pass:no)

=item *

C<<< edit_report = <grade:action> ... >>> -- edit the test report before sending? 
(default:askE<sol>no pass:no)

=item *

C<<< send_report = <grade:action> ... >>> -- should test reports be sent at all?
(default:askE<sol>yes pass:yes na:no)

=item *

C<<< send_duplicates = <grade:action> ... >>> -- should duplicates of previous 
reports be sent, regardless of C<<< send_report >>>? (default:no)

=back

These options are included in the starter config file created automatically the
first time CPAN::Reporter is configured interactively.

Note that if C<<< send_report >>> is set to "no", CPAN::Reporter will still go through
the motions of preparing a report, but will discard it rather than send it.
This is the default for an "na" report -- users may still edit the report to 
see which prerequisites failed, but no report will be sent.

A better way to disable CPAN::Reporter temporarily is with the CPAN option
C<<< test_report >>>:

  cpan> o conf test_report 0

=head2 Mail Server

By default, Test::Reporter attempts to send mail directly to perl.org mail 
servers.  This may fail if a user's computer is behind a network firewall 
that blocks outbound email.  In this case, the following option should
be set to the outbound mail server (i.e., SMTP server) as provided by
the user's Internet service provider (ISP):

=over

=item *

C<<< smtp_server = <server list> >>> -- one or more alternate outbound mail servers
if the default perl.org mail servers cannot be reached; multiple servers may be
given, separated with a space (none by default)

=back

In at least one reported case, an ISP's outbound mail servers also refused 
to forward mail unless the C<<< email_from >>> was from the ISP-given email address. 

This option is also included in the starter config file.

=head2 Additional Options

These additional options are only necessary in special cases, such as for
testing, debugging or if a default editor cannot be found.

=over

=item *

C<<< email_to = <email address> >>> -- alternate destination for reports instead of
C<<< cpan-testers@perl.org >>>; used for testing

=item *

C<<< editor = <editor> >>> -- editor to use to edit the test report; if not set,
Test::Reporter will use environment variables C<<< VISUAL >>>, C<<< EDITOR >>> or C<<< EDIT >>>
(in that order) to find an editor 

=item *

C<<< debug = <boolean> >>> -- turns debugging onE<sol>off

=back

=head1 FUNCTIONS

CPAN::Reporter provides only two public function for use within CPAN.pm.
They are not imported during C<<< use >>>.  Ordinary users will never need them.

=head2 C<<< configure() >>>

  CPAN::Reporter::configure();

Prompts the user to edit configuration settings stored in the CPAN::Reporter
C<<< config.ini >>> file.  It will create the configuration file if it does not exist.
It is automatically called by CPAN.pm when initializing the 'test_report'
option, e.g.:

  cpan> o conf init test_report

=head2 C<<< test() >>>

  CPAN::Reporter::test( $cpan_dist, $system_command );

Given a CPAN::Distribution object and a system command to run distribution
tests (e.g. "make test"), C<<< test() >>> executes the command via C<<< system() >>> while
teeing the output to a file.  Based on the output captured in the file,
C<<< test() >>> generates and sends a L<Test::Reporter> report.  It returns true if
the test grade is "pass" or "unknown" and returns false, otherwise.

=head1 PRIVACY WARNING

CPAN::Reporter includes information in the test report about environment
variables and special Perl variables that could be affecting test results in
order to help module authors interpret the results of the tests.  This includes
information about paths, terminal, locale, userE<sol>group ID, installed toolchain
modules (e.g. ExtUtils::MakeMaker) and so on.  

These have been intentionally limited to items that should not cause harmful
personal information to be revealed -- it does I<not> include your entire
environment.  Nevertheless, please do not use CPAN::Reporter if you are
concerned about the disclosure of this information as part of your test report.  

Users wishing to review this information may choose to edit the report 
prior to sending it.

=head1 BUGS

Please report any bugs or feature using the CPAN Request Tracker.  
Bugs can be submitted through the web interface at 
L<http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Reporter>

When submitting a bug or request, please include a test-file or a patch to an
existing test-file that illustrates the bug or desired feature.

=head1 AUTHOR

David A. Golden (DAGOLDEN)

dagolden@cpan.org

http:E<sol>E<sol>www.dagolden.orgE<sol>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2006, 2007 by David A. Golden

This program is free software; you can redistribute
it andE<sol>or modify it under the same terms as Perl itself.

The full text of the license can be found in the
LICENSE file included with this module.

=head1 DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS ANDE<sol>OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY ANDE<sol>OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.


