README
1NAME
2 CPAN::Reporter - Adds CPAN Testers reporting to CPAN.pm
3
4VERSION
5 version 1.2018
6
7SYNOPSIS
8 From the CPAN shell:
9
10 cpan> install Task::CPAN::Reporter
11 cpan> reload cpan
12 cpan> o conf init test_report
13
14 Installing Task::CPAN::Reporter will pull in additional dependencies
15 that new CPAN Testers will need.
16
17 Advanced CPAN Testers with custom Test::Reporter::Transport setups may
18 wish to install only CPAN::Reporter, which has fewer dependencies.
19
20DESCRIPTION
21 The CPAN Testers project captures and analyzes detailed results from
22 building and testing CPAN distributions on multiple operating systems
23 and multiple versions of Perl. This provides valuable feedback to module
24 authors and potential users to identify bugs or platform compatibility
25 issues and improves the overall quality and value of CPAN.
26
27 One way individuals can contribute is to send a report for each module
28 that they test or install. CPAN::Reporter is an add-on for the CPAN.pm
29 module to send the results of building and testing modules to the CPAN
30 Testers project. Full support for CPAN::Reporter is available in CPAN.pm
31 as of version 1.92.
32
33GETTING STARTED
34 Installation
35 The first step in using CPAN::Reporter is to install it using whatever
36 version of CPAN.pm is already installed. CPAN.pm will be upgraded as a
37 dependency if necessary.
38
39 cpan> install CPAN::Reporter
40
41 If CPAN.pm was upgraded, it needs to be reloaded.
42
43 cpan> reload cpan
44
45 Configuration
46 If upgrading from a very old version of CPAN.pm, users may be prompted
47 to renew their configuration settings, including the 'test_report'
48 option to enable CPAN::Reporter.
49
50 If not prompted automatically, users should manually initialize
51 CPAN::Reporter support. After enabling CPAN::Reporter, CPAN.pm will
52 automatically continue with interactive configuration of CPAN::Reporter
53 options.
54
55 cpan> o conf init test_report
56
57 Users will need to enter an email address in one of the following
58 formats:
59
60 johndoe@example.com
61 John Doe <johndoe@example.com>
62 "John Q. Public" <johnqpublic@example.com>
63
64 Users that are new to CPAN::Reporter should accept the recommended
65 values for other configuration options.
66
67 Users will be prompted to create a *Metabase profile* file that uniquely
68 identifies their test reports. See "The Metabase" below for details.
69
70 After completing interactive configuration, be sure to commit (save) the
71 CPAN configuration changes.
72
73 cpan> o conf commit
74
75 See CPAN::Reporter::Config for advanced configuration settings.
76
77 The Metabase
78 CPAN::Reporter sends test reports to a server known as the Metabase.
79 This requires an active Internet connection and a profile file. To
80 create the profile, users will need to run "metabase-profile" from a
81 terminal window and fill the information at the prompts. This will
82 create a file called "metabase_id.json" in the current directory. That
83 file should be moved to the ".cpanreporter" directory inside the user's
84 home directory.
85
86 Users with an existing metabase profile file (e.g. from another
87 machine), should copy it into the ".cpanreporter" directory instead of
88 creating a new one. Profile files may be located outside the
89 ".cpanreporter" directory by following instructions in
90 CPAN::Reporter::Config.
91
92 Default Test Comments
93 This module puts default text into the "TESTER COMMENTS" section,
94 typically, "none provided" if doing interactive testing, or, if doing
95 smoke testing that sets C<$ENV{AUTOMATED_TESTING}> to a true value,
96 "this report is from an automated smoke testing program and was not
97 reviewed by a human for accuracy." If C<CPAN::Reporter> is configured to
98 allow editing of the report, this can be edited during submission.
99
100 If you wish to override the default comment, you can create a file named
101 C<comment.txt> in the configuration directory (typically ".cpanreporter"
102 under the user's home directory), with the default comment you would
103 like to appear.
104
105 Note that if your test is an automated smoke test
106 (C<$ENV{AUTOMATED_TESTING}> is set to a true value), the smoke test
107 notice ("this report is from an automated smoke testing program and was
108 not reviewed by a human for accuracy") is included along with a blank
109 line before your C<comment.txt>, so that it is always possible to
110 distinguish automated tests from non-automated tests that use this
111 module.
112
113 Using CPAN::Reporter
114 Once CPAN::Reporter is enabled and configured, test or install modules
115 with CPAN.pm as usual.
116
117 For example, to test the File::Marker module:
118
119 cpan> test File::Marker
120
121 If a distribution's tests fail, users will be prompted to edit the
122 report to add additional information that might help the author
123 understand the failure.
124
125UNDERSTANDING TEST GRADES
126 CPAN::Reporter will assign one of the following grades to the report:
127
128 * "pass" -- distribution built and tested correctly
129
130 * "fail" -- distribution failed to test correctly
131
132 * "unknown" -- distribution failed to build, had no test suite or
133 outcome was inconclusive
134
135 * "na" --- distribution is not applicable to this platform and/or
136 version of Perl
137
138 In returning results of the test suite to CPAN.pm, "pass" and "unknown"
139 are considered successful attempts to "make test" or "Build test" and
140 will not prevent installation. "fail" and "na" are considered to be
141 failures and CPAN.pm will not install unless forced.
142
143 An error from Makefile.PL/Build.PL or make/Build will also be graded as
144 "unknown" and a failure will be signaled to CPAN.pm.
145
146 If prerequisites specified in "Makefile.PL" or "Build.PL" are not
147 available, no report will be generated and a failure will be signaled to
148 CPAN.pm.
149
150PRIVACY WARNING
151 CPAN::Reporter includes information in the test report about environment
152 variables and special Perl variables that could be affecting test
153 results in order to help module authors interpret the results of the
154 tests. This includes information about paths, terminal, locale,
155 user/group ID, installed toolchain modules (e.g. ExtUtils::MakeMaker)
156 and so on.
157
158 These have been intentionally limited to items that should not cause
159 harmful personal information to be revealed -- it does *not* include
160 your entire environment. Nevertheless, please do not use CPAN::Reporter
161 if you are concerned about the disclosure of this information as part of
162 your test report.
163
164 Users wishing to review this information may choose to edit the report
165 prior to sending it.
166
167BUGS
168 Using command_timeout on Linux may cause problems. See
169 <https://rt.cpan.org/Ticket/Display.html?id=62310>
170
171 Please report any bugs or feature using the CPAN Request Tracker. Bugs
172 can be submitted through the web interface at
173 <http://rt.cpan.org/Dist/Display.html?Queue=CPAN-Reporter>
174
175 When submitting a bug or request, please include a test-file or a patch
176 to an existing test-file that illustrates the bug or desired feature.
177
178SEE ALSO
179 Information about CPAN::Testers:
180
181 * CPAN::Testers -- overview of CPAN Testers architecture stack
182
183 * <http://www.cpantesters.org> -- project home with all reports
184
185 * <http://wiki.cpantesters.org> -- documentation and wiki
186
187 Additional Documentation:
188
189 * CPAN::Reporter::Config -- advanced configuration settings
190
191 * CPAN::Reporter::FAQ -- hints and tips
192
193SUPPORT
194 Bugs / Feature Requests
195 Please report any bugs or feature requests through the issue tracker at
196 <https://github.com/cpan-testers/CPAN-Reporter/issues>. You will be
197 notified automatically of any progress on your issue.
198
199 Source Code
200 This is open source software. The code repository is available for
201 public review and contribution under the terms of the license.
202
203 <https://github.com/cpan-testers/CPAN-Reporter>
204
205 git clone https://github.com/cpan-testers/CPAN-Reporter.git
206
207AUTHOR
208 David Golden <dagolden@cpan.org>
209
210CONTRIBUTORS
211 * Alexandr Ciornii <alexchorny@gmail.com>
212
213 * Breno G. de Oliveira <garu@cpan.org>
214
215 * Christian Walde <walde.christian@googlemail.com>
216
217 * Ed J <mohawk2@users.noreply.github.com>
218
219 * Joel Maslak <jmaslak@antelope.net>
220
221 * Kent Fredric <kentfredric@gmail.com>
222
223 * Matthew Musgrove <mr.muskrat@gmail.com>
224
225 * Patrice Clement <monsieurp@gentoo.org>
226
227 * Reini Urban <rurban@cpanel.net>
228
229 * Scott Wiersdorf <scott@perlcode.org>
230
231 * Slaven Rezic <slaven@rezic.de>
232
233COPYRIGHT AND LICENSE
234 This software is Copyright (c) 2006 by David Golden.
235
236 This is free software, licensed under:
237
238 The Apache License, Version 2.0, January 2004
239
240