Debian Codegraph @

upstream/opensuse-tumbleweed/man1/perlthanks.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLBUG 1"
61 .TH PERLBUG 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlbug \- how to submit bug reports on Perl
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 \&\fBperlbug\fR
71 .PP
72 \&\fBperlbug\fR [\ \fB\-v\fR\ ] [\ \fB\-a\fR\ \fIaddress\fR\ ] [\ \fB\-s\fR\ \fIsubject\fR\ ]
73 [\ \fB\-b\fR\ \fIbody\fR\ |\ \fB\-f\fR\ \fIinputfile\fR\ ] [\ \fB\-F\fR\ \fIoutputfile\fR\ ]
74 [\ \fB\-r\fR\ \fIreturnaddress\fR\ ]
75 [\ \fB\-e\fR\ \fIeditor\fR\ ] [\ \fB\-c\fR\ \fIadminaddress\fR\ |\ \fB\-C\fR\ ]
76 [\ \fB\-S\fR\ ] [\ \fB\-t\fR\ ] [\ \fB\-d\fR\ ] [\ \fB\-h\fR\ ] [\ \fB\-T\fR\ ]
77 .PP
78 \&\fBperlbug\fR [\ \fB\-v\fR\ ] [\ \fB\-r\fR\ \fIreturnaddress\fR\ ]
79 [\ \fB\-ok\fR\ |\ \fB\-okay\fR\ |\ \fB\-nok\fR\ |\ \fB\-nokay\fR\ ]
80 .PP
81 \&\fBperlthanks\fR
82 .SH DESCRIPTION
83 .IX Header "DESCRIPTION"
84 This program is designed to help you generate bug reports
85 (and thank\-you notes) about perl5 and the modules which ship with it.
86 .PP
87 In most cases, you can just run it interactively from a command
88 line without any special arguments and follow the prompts.
89 .PP
90 If you have found a bug with a non\-standard port (one that was not
91 part of the \fIstandard distribution\fR), a binary distribution, or a
92 non\-core module (such as Tk, DBI, etc), then please see the
93 documentation that came with that distribution to determine the
94 correct place to report bugs.
95 .PP
96 Bug reports should be submitted to the GitHub issue tracker at
97 <https://github.com/Perl/perl5/issues>. The \[email protected]\fR
98 address no longer automatically opens tickets. You can use this tool
99 to compose your report and save it to a file which you can then submit
100 to the issue tracker.
101 .PP
102 In extreme cases, \fBperlbug\fR may not work well enough on your system
103 to guide you through composing a bug report. In those cases, you
104 may be able to use \fBperlbug \-d\fR or \fBperl \-V\fR to get system
105 configuration information to include in your issue report.
106 .PP
107 When reporting a bug, please run through this checklist:
108 .IP "What version of Perl you are running?" 4
109 .IX Item "What version of Perl you are running?"
110 Type \f(CW\*(C`perl \-v\*(C'\fR at the command line to find out.
111 .IP "Are you running the latest released version of perl?" 4
112 .IX Item "Are you running the latest released version of perl?"
113 Look at <http://www.perl.org/> to find out. If you are not using the
114 latest released version, please try to replicate your bug on the
115 latest stable release.
116 .Sp
117 Note that reports about bugs in old versions of Perl, especially
118 those which indicate you haven\*(Aqt also tested the current stable
119 release of Perl, are likely to receive less attention from the
120 volunteers who build and maintain Perl than reports about bugs in
121 the current release.
122 .IP "Are you sure what you have is a bug?" 4
123 .IX Item "Are you sure what you have is a bug?"
124 A significant number of the bug reports we get turn out to be
125 documented features in Perl. Make sure the issue you\*(Aqve run into
126 isn\*(Aqt intentional by glancing through the documentation that comes
127 with the Perl distribution.
128 .Sp
129 Given the sheer volume of Perl documentation, this isn\*(Aqt a trivial
130 undertaking, but if you can point to documentation that suggests
131 the behaviour you\*(Aqre seeing is \fIwrong\fR, your issue is likely to
132 receive more attention. You may want to start with \fBperldoc\fR
133 perltrap for pointers to common traps that new (and experienced)
134 Perl programmers run into.
135 .Sp
136 If you\*(Aqre unsure of the meaning of an error message you\*(Aqve run
137 across, \fBperldoc\fR perldiag for an explanation. If the message
138 isn\*(Aqt in perldiag, it probably isn\*(Aqt generated by Perl. You may
139 have luck consulting your operating system documentation instead.
140 .Sp
141 If you are on a non\-UNIX platform \fBperldoc\fR perlport, as some
142 features may be unimplemented or work differently.
143 .Sp
144 You may be able to figure out what\*(Aqs going wrong using the Perl
145 debugger. For information about how to use the debugger \fBperldoc\fR
146 perldebug.
147 .IP "Do you have a proper test case?" 4
148 .IX Item "Do you have a proper test case?"
149 The easier it is to reproduce your bug, the more likely it will be
150 fixed \-\- if nobody can duplicate your problem, it probably won\*(Aqt be
151 addressed.
152 .Sp
153 A good test case has most of these attributes: short, simple code;
154 few dependencies on external commands, modules, or libraries; no
155 platform\-dependent code (unless it\*(Aqs a platform\-specific bug);
156 clear, simple documentation.
157 .Sp
158 A good test case is almost always a good candidate to be included in
159 Perl\*(Aqs test suite. If you have the time, consider writing your test case so
160 that it can be easily included into the standard test suite.
161 .IP "Have you included all relevant information?" 4
162 .IX Item "Have you included all relevant information?"
163 Be sure to include the \fBexact\fR error messages, if any.
164 "Perl gave an error" is not an exact error message.
165 .Sp
166 If you get a core dump (or equivalent), you may use a debugger
167 (\fBdbx\fR, \fBgdb\fR, etc) to produce a stack trace to include in the bug
168 report.
169 .Sp
170 NOTE: unless your Perl has been compiled with debug info
171 (often \fB\-g\fR), the stack trace is likely to be somewhat hard to use
172 because it will most probably contain only the function names and not
173 their arguments. If possible, recompile your Perl with debug info and
174 reproduce the crash and the stack trace.
175 .IP "Can you describe the bug in plain English?" 4
176 .IX Item "Can you describe the bug in plain English?"
177 The easier it is to understand a reproducible bug, the more likely
178 it will be fixed. Any insight you can provide into the problem
179 will help a great deal. In other words, try to analyze the problem
180 (to the extent you can) and report your discoveries.
181 .IP "Can you fix the bug yourself?" 4
182 .IX Item "Can you fix the bug yourself?"
183 If so, that\*(Aqs great news; bug reports with patches are likely to
184 receive significantly more attention and interest than those without
185 patches. Please submit your patch via the GitHub Pull Request workflow
186 as described in \fBperldoc\fR perlhack. You may also send patches to
187 \&\fBperl5\[email protected]\fR. When sending a patch, create it using
188 \&\f(CW\*(C`git format\-patch\*(C'\fR if possible, though a unified diff created with
189 \&\f(CW\*(C`diff \-pu\*(C'\fR will do nearly as well.
190 .Sp
191 Your patch may be returned with requests for changes, or requests for more
192 detailed explanations about your fix.
193 .Sp
194 Here are a few hints for creating high\-quality patches:
195 .Sp
196 Make sure the patch is not reversed (the first argument to diff is
197 typically the original file, the second argument your changed file).
198 Make sure you test your patch by applying it with \f(CW\*(C`git am\*(C'\fR or the
199 \&\f(CW\*(C`patch\*(C'\fR program before you send it on its way. Try to follow the
200 same style as the code you are trying to patch. Make sure your patch
201 really does work (\f(CW\*(C`make test\*(C'\fR, if the thing you\*(Aqre patching is covered
202 by Perl\*(Aqs test suite).
203 .ie n .IP "Can you use ""perlbug"" to submit a thank\-you note?" 4
204 .el .IP "Can you use \f(CWperlbug\fR to submit a thank\-you note?" 4
205 .IX Item "Can you use perlbug to submit a thank-you note?"
206 Yes, you can do this by either using the \f(CW\*(C`\-T\*(C'\fR option, or by invoking
207 the program as \f(CW\*(C`perlthanks\*(C'\fR. Thank\-you notes are good. It makes people
208 smile.
209 .PP
210 Please make your issue title informative. "a bug" is not informative.
211 Neither is "perl crashes" nor is "HELP!!!". These don\*(Aqt help. A compact
212 description of what\*(Aqs wrong is fine.
213 .PP
214 Having done your bit, please be prepared to wait, to be told the
215 bug is in your code, or possibly to get no reply at all. The
216 volunteers who maintain Perl are busy folks, so if your problem is
217 an obvious bug in your own code, is difficult to understand or is
218 a duplicate of an existing report, you may not receive a personal
219 reply.
220 .PP
221 If it is important to you that your bug be fixed, do monitor the
222 issue tracker (you will be subscribed to notifications for issues you
223 submit or comment on) and the commit logs to development
224 versions of Perl, and encourage the maintainers with kind words or
225 offers of frosty beverages. (Please do be kind to the maintainers.
226 Harassing or flaming them is likely to have the opposite effect of the
227 one you want.)
228 .PP
229 Feel free to update the ticket about your bug on
230 <https://github.com/Perl/perl5/issues>
231 if a new version of Perl is released and your bug is still present.
232 .SH OPTIONS
233 .IX Header "OPTIONS"
234 .IP \fB\-a\fR 8
235 .IX Item "-a"
236 Address to send the report to instead of saving to a file.
237 .IP \fB\-b\fR 8
238 .IX Item "-b"
239 Body of the report. If not included on the command line, or
240 in a file with \fB\-f\fR, you will get a chance to edit the report.
241 .IP \fB\-C\fR 8
242 .IX Item "-C"
243 Don\*(Aqt send copy to administrator when sending report by mail.
244 .IP \fB\-c\fR 8
245 .IX Item "-c"
246 Address to send copy of report to when sending report by mail.
247 Defaults to the address of the
248 local perl administrator (recorded when perl was built).
249 .IP \fB\-d\fR 8
250 .IX Item "-d"
251 Data mode (the default if you redirect or pipe output). This prints out
252 your configuration data, without saving or mailing anything. You can use
253 this with \fB\-v\fR to get more complete data.
254 .IP \fB\-e\fR 8
255 .IX Item "-e"
256 Editor to use.
257 .IP \fB\-f\fR 8
258 .IX Item "-f"
259 File containing the body of the report. Use this to quickly send a
260 prepared report.
261 .IP \fB\-F\fR 8
262 .IX Item "-F"
263 File to output the results to. Defaults to \fBperlbug.rep\fR.
264 .IP \fB\-h\fR 8
265 .IX Item "-h"
266 Prints a brief summary of the options.
267 .IP \fB\-ok\fR 8
268 .IX Item "-ok"
269 Report successful build on this system to perl porters. Forces \fB\-S\fR
270 and \fB\-C\fR. Forces and supplies values for \fB\-s\fR and \fB\-b\fR. Only
271 prompts for a return address if it cannot guess it (for use with
272 \&\fBmake\fR). Honors return address specified with \fB\-r\fR. You can use this
273 with \fB\-v\fR to get more complete data. Only makes a report if this
274 system is less than 60 days old.
275 .IP \fB\-okay\fR 8
276 .IX Item "-okay"
277 As \fB\-ok\fR except it will report on older systems.
278 .IP \fB\-nok\fR 8
279 .IX Item "-nok"
280 Report unsuccessful build on this system. Forces \fB\-C\fR. Forces and
281 supplies a value for \fB\-s\fR, then requires you to edit the report
282 and say what went wrong. Alternatively, a prepared report may be
283 supplied using \fB\-f\fR. Only prompts for a return address if it
284 cannot guess it (for use with \fBmake\fR). Honors return address
285 specified with \fB\-r\fR. You can use this with \fB\-v\fR to get more
286 complete data. Only makes a report if this system is less than 60
287 days old.
288 .IP \fB\-nokay\fR 8
289 .IX Item "-nokay"
290 As \fB\-nok\fR except it will report on older systems.
291 .IP \fB\-p\fR 8
292 .IX Item "-p"
293 The names of one or more patch files or other text attachments to be
294 included with the report. Multiple files must be separated with commas.
295 .IP \fB\-r\fR 8
296 .IX Item "-r"
297 Your return address. The program will ask you to confirm its default
298 if you don\*(Aqt use this option.
299 .IP \fB\-S\fR 8
300 .IX Item "-S"
301 Save or send the report without asking for confirmation.
302 .IP \fB\-s\fR 8
303 .IX Item "-s"
304 Subject to include with the report. You will be prompted if you don\*(Aqt
305 supply one on the command line.
306 .IP \fB\-t\fR 8
307 .IX Item "-t"
308 Test mode. Makes it possible to command perlbug from a pipe or file, for
309 testing purposes.
310 .IP \fB\-T\fR 8
311 .IX Item "-T"
312 Send a thank\-you note instead of a bug report.
313 .IP \fB\-v\fR 8
314 .IX Item "-v"
315 Include verbose configuration data in the report.
316 .SH AUTHORS
317 .IX Header "AUTHORS"
318 Kenneth Albanowski (<[email protected]>), subsequently
319 \&\fIdoc\fRtored by Gurusamy Sarathy (<[email protected]>),
320 Tom Christiansen (<[email protected]>), Nathan Torkington
321 (<[email protected]>), Charles F. Randall (<[email protected]>),
322 Mike Guy (<[email protected]>), Dominic Dunlop
323 (<[email protected]>), Hugo van der Sanden (<[email protected]>),
324 Jarkko Hietaniemi (<[email protected]>), Chris Nandor
325 (<[email protected]>), Jon Orwant (<[email protected]>,
326 Richard Foley (<[email protected]>), Jesse Vincent
327 (<[email protected]>), and Craig A. Berry (<[email protected]>).
328 .SH "SEE ALSO"
329 .IX Header "SEE ALSO"
330 \&\fBperl\fR\|(1), \fBperldebug\fR\|(1), \fBperldiag\fR\|(1), \fBperlport\fR\|(1), \fBperltrap\fR\|(1),
331 \&\fBdiff\fR\|(1), \fBpatch\fR\|(1), \fBdbx\fR\|(1), \fBgdb\fR\|(1)
332 .SH BUGS
333 .IX Header "BUGS"
334 None known (guess what must have been used to report them?)