Debian Codegraph @

README

raw
1 NAME
2 CPAN::Reporter - Adds CPAN Testers reporting to CPAN.pm
3
4 VERSION
5 version 1.2020
6
7 SYNOPSIS
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
20 DESCRIPTION
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
33 GETTING 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 [email protected]
61 John Doe <[email protected]>
62 "John Q. Public" <[email protected]>
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
125 UNDERSTANDING 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
150 PRIVACY 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
167 BUGS
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
178 SEE 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
193 SUPPORT
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
207 AUTHOR
208 David Golden <[email protected]>
209
210 CONTRIBUTORS
211 * Alexandr Ciornii <[email protected]>
212
213 * Breno G. de Oliveira <[email protected]>
214
215 * Christian Walde <[email protected]>
216
217 * David Cantrell <[email protected]>
218
219 * Ed J <[email protected]>
220
221 * Graham Knop <[email protected]>
222
223 * HÃ¥kon Hægland <[email protected]>
224
225 * James E Keenan <[email protected]>
226
227 * J. Maslak <[email protected]>
228
229 * José Joaquín Atria <[email protected]>
230
231 * Kent Fredric <[email protected]>
232
233 * Leon Timmermans <[email protected]>
234
235 * Matthew Musgrove <[email protected]>
236
237 * Patrice Clement <[email protected]>
238
239 * Reini Urban <[email protected]>
240
241 * Scott Wiersdorf <[email protected]>
242
243 * Slaven Rezic <[email protected]>
244
245 COPYRIGHT AND LICENSE
246 This software is Copyright (c) 2023 by David Golden.
247
248 This is free software, licensed under:
249
250 The Apache License, Version 2.0, January 2004
251