| # Generated by Pod::WikiDoc version 0.18 |
| |
| =pod |
| |
| =head1 NAME |
| |
| CPAN::Reporter::Config - Config file options for CPAN::Reporter |
| |
| =head1 VERSION |
| |
| This documentation refers to version 1.13 |
| |
| =head1 SYNOPSIS |
| |
| From the CPAN shell: |
| |
| cpan> o conf init test_report |
| |
| =head1 DESCRIPTION |
| |
| 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, mail server and common |
| action prompts may be repeated at any time from the CPAN shell. |
| |
| cpan> o conf init test_report |
| |
| If a configuration file does not exist, it will be created the first |
| time interactive configuration is performed. |
| |
| Subsequent interactive configuration will also include any advanced |
| options that have been added manually to the configuration file. |
| |
| =head1 INTERACTIVE CONFIGURATION OPTIONS |
| |
| =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 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. |
| |
| =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 included in interactive configuration are: |
| |
| =over |
| |
| =item * |
| |
| C<<< edit_report = <grade:action> ... >>> -- edit the test report before sending? |
| (default:askE<sol>no passE<sol>na:no) |
| |
| =item * |
| |
| C<<< send_report = <grade:action> ... >>> -- should test reports be sent at all? |
| (default:askE<sol>yes passE<sol>na:yes) |
| |
| =back |
| |
| 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. |
| |
| A better way to disable CPAN::Reporter temporarily is with the CPAN option |
| C<<< test_report >>>: |
| |
| cpan> o conf test_report 0 |
| |
| =head1 ADVANCED CONFIGURATION OPTIONS |
| |
| These additional options are only necessary in special cases, for example if |
| the default editor cannot be found or if reports shouldn't be sent in |
| certain situations or for automated testing, and so on. |
| |
| =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 passE<sol>na:no) |
| |
| =item * |
| |
| C<<< cc_skipfile = <skipfile> >>> -- filename containing regular expressions (one |
| per line) to match against the distribution ID (e.g. |
| 'AUTHORE<sol>Dist-Name-0.01.tar.gz'); the author will not be copied if a match is |
| found regardless of cc_author; non-absolute filename must be in the .cpanreporter |
| config directory; |
| |
| =item * |
| |
| C<<< command_timeout >>> -- if greater than zero and the CPAN config is |
| C<<< inactivity_timeout >>> is not set, then any commands executed by CPAN::Reporter |
| will be halted after this many seconds; useful for unattended smoke testing |
| to stop after some amount of time; generally, this should be large -- |
| 900 seconds or more -- as some distributions' tests take quite a long time to |
| run. On MSWin32, L<Win32::Job> is a needed and trying to kill a processes may |
| actually deadlock in some situations -- so use at your own risk |
| |
| =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<<< send_duplicates = <grade:action> ... >>> -- should duplicates of previous |
| reports be sent, regardless of C<<< send_report >>>? (default:no) |
| |
| =item * |
| |
| C<<< send_PL_report = <grade:action> ... >>> -- if defined, used in place of |
| C<<< send_report >>> during the PL phase |
| |
| =item * |
| |
| C<<< send_make_report = <grade:action> ... >>> -- if defined, used in place of |
| C<<< send_report >>> during the make phase |
| |
| =item * |
| |
| C<<< send_test_report = <grade:action> ... >>> -- if defined, used in place of |
| C<<< send_report >>> during the test phase |
| |
| =item * |
| |
| C<<< send_skipfile = <skipfile> >>> -- like C<<< cc_skipfile >>> but no report will be |
| sent at all if a match is found |
| |
| =item * |
| |
| C<<< transport = <transport> >>> -- if defined, passed to the C<<< transport() >>> |
| method of L<Test::Reporter>. Valid options are 'Net::SMTP' or |
| 'Mail::Send'. (CPAN::Reporter uses Net::SMTP for this by default.) |
| |
| =back |
| |
| If these options are manually added to the configuration file, they will |
| be included (and preserved) in subsequent interactive configuration. |
| |
| =head2 Skipfile regular expressions |
| |
| Skip files are expected to have one regular expression per line and will be |
| matched against the distribution ID, composed of the author's CPAN ID and the |
| distribution tarball name. |
| |
| DAGOLDEN/CPAN-Reporter-1.00.tar.gz |
| |
| Lines that begin with a sharp (#) are considered comments and will not be |
| matched. All regular expressionss will be matched case insensitive and will |
| not be anchored unless you provide one. |
| |
| As the format of a distribution ID is "AUTHORE<sol>tarball", anchoring at the |
| start of the line with a caret (^) will match the author and with a slash (E<sol>) |
| will match the distribution. |
| |
| # any distributions by JOHNDOE |
| ^JOHNDOE |
| # any distributions starting with Win32 |
| /Win32 |
| # a particular very specific distribution |
| ^JOHNDOE/Foo-Bar-3.14 |
| |
| =head1 CONFIGURATION OPTIONS FOR DEBUGGING |
| |
| These options are useful for debugging only: |
| |
| =over |
| |
| =item * |
| |
| C<<< debug = <boolean> >>> -- turns debugging onE<sol>off |
| |
| =item * |
| |
| C<<< email_to = <email address> >>> -- alternate destination for reports instead of |
| C<<< cpan-testers@perl.org >>>; used for testing |
| |
| =back |
| |
| =head1 ENVIRONMENT |
| |
| The following environment variables may be set to alter the default locations |
| for CPAN::Reporter files: |
| |
| =over |
| |
| =item * |
| |
| C<<< PERL_CPAN_REPORTER_DIR >>> -- if set, this directory is used in place of |
| the default .cpanreporter directory; this will affect not only the location |
| of the default C<<< config.ini >>>, but also the location of the |
| L<CPAN::Reporter::History> database and any other files that live in that |
| directory |
| |
| =item * |
| |
| C<<< PERL_CPAN_REPORTER_CONFIG >>> -- if set, this file is used in place of |
| the default C<<< config.ini >>> file; it may be in any directory, regardless of the |
| choice of configuration directory |
| |
| =back |
| |
| =head1 SEE ALSO |
| |
| =over |
| |
| =item * |
| |
| L<CPAN::Reporter> |
| |
| =item * |
| |
| L<CPAN::Reporter::History> |
| |
| =item * |
| |
| L<CPAN::Reporter::FAQ> |
| |
| =back |
| |
| =head1 AUTHOR |
| |
| David A. Golden (DAGOLDEN) |
| |
| =head1 COPYRIGHT AND LICENSE |
| |
| Copyright (c) 2006, 2007, 2008 by David A. Golden |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| L<http://www.apache.org/licenses/LICENSE-2.0> |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| |
| |