Build a Reproducible Perl Bug Report with perlbug

You will finish with a short Perl bug report saved locally, containing the exact failure, a minimal test case and the configuration data maintainers need. This guide uses perlbug from the Ubuntu perl package, version 5.38.2-3.2ubuntu0.6, with Perl v5.38.2. Allow about fifteen minutes if you already have a failing example.

The commands below compose and save a report. They do not require elevated privileges and do not submit anything unless you deliberately choose to send it. The installed manpage says Perl bug reports now belong in the Perl GitHub issue tracker; the old [email protected] address no longer opens tickets automatically.

1. Confirm that the problem belongs to Perl

First check the interpreter and the command you are about to use:

$ command -v perl perlbug
/usr/bin/perl
/usr/bin/perlbug
$ perl -v
This is perl 5, version 38, subversion 2 (v5.38.2) built for x86_64-linux-gnu-thread-multi

Reproduce the problem on the latest stable Perl when possible. Check the bundled documentation before reporting a documented feature, an error explained by perldoc perldiag, or behaviour specific to a non-core module such as DBI or Tk. Non-standard ports and binary distributions should use their own support route.

2. Reduce the failure to a test case

Put the smallest useful example in a file. Replace the example with your own failing code, but keep its input and expected result visible:

$ mkdir -p "$HOME/perlbug-case"
$ cd "$HOME/perlbug-case"
$ editor reproduce.pl
$ perl reproduce.pl
expected: 3
actual: 4

A good case has few dependencies, little platform-specific code and no secrets. Record the exact command, complete error text, operating system, Perl version and whether a module or external program is involved. If the issue is a crash, a debugger stack trace may help. A Perl built without debug information can produce a less useful trace.

The directory and file above are ordinary user-owned test data. If you later decide the case contains credentials or personal data, remove those values before attaching or pasting it. Do not send private keys, access tokens or customer data to a public issue tracker.

3. Capture configuration without sending a report

Data mode prints configuration and saves nothing. It is useful when the interactive report tool cannot run correctly:

$ perlbug -d > perlbug-config.txt
$ sed -n '1,18p' perlbug-config.txt
**Flags
- category=core
- severity=low
**Perl configuration
Site configuration information for perl 5.38.2:

For more detail, add -v:

$ perlbug -v -d > perlbug-config-verbose.txt
$ test -s perlbug-config-verbose.txt && echo 'configuration captured'
configuration captured

Inspect these files before sharing them. Configuration output can reveal host names, paths, compiler arguments and local patch information. Data mode is read-only, so there is no rollback step.

4. Prepare the report body

Write a plain-text body with a clear sequence. The following is a safe template; replace every bracketed value before continuing:

What I expected:
[one sentence]

What happened:
[exact output or error]

Reproduction:
[complete command and the smallest code example]

Environment:
Perl [output from perl -v]
OS: [distribution and release]
Module versions: [relevant versions]

Additional observations:
[whether another Perl release or platform behaves differently]

Save it as body.txt in the case directory and check that it is not empty:

$ test -s body.txt && echo 'report body is ready'
report body is ready

Use an informative subject such as Regexp match changes after repeated capture reset. Avoid subjects such as a bug, Perl crashes or HELP!!!; they do not help triage.

5. Let perlbug assemble and save the report

Use -f for the prepared body, -s for the subject and -F for an explicit output file:

$ perlbug -f body.txt \
    -s 'Regexp match changes after repeated capture reset' \
    -F perlbug-report.txt
Subject: Regexp match changes after repeated capture reset
Action (Send/Display/Edit/Subject/Save to File):

At the prompt, choose the save-to-file action and accept the displayed output path, or choose display first and inspect the complete report. The exact prompt wording can vary with the installed Perl build. The program may ask you to confirm a return address; use -r [email protected] when you need to supply one explicitly.

6. Review, attach and submit deliberately

Inspect the saved report with a pager:

$ less perlbug-report.txt
$ grep -n -E 'What I expected|What happened|Reproduction|Perl configuration' perlbug-report.txt
perlbug-report.txt:...:What I expected:
perlbug-report.txt:...:What happened:
perlbug-report.txt:...:Reproduction:
perlbug-report.txt:...:Perl configuration

The line numbers are variable. If you have a patch, -p patch-file can include one or more comma-separated patch files in the report. Check the patch and test it before sharing it. A saved report is reversible: edit or delete the local file with ordinary file tools. Sending a public issue is not reversible in the same way, so remove secrets first and submit through the Perl tracker rather than relying on the obsolete automatic email path.

For a thank-you note, invoke perlthanks or use perlbug -T. The alias is still installed here, but it is a different purpose from reporting a defect. Build-status reports use -ok, -okay, -nok or -nokay; use those only for the corresponding Perl build outcome.