Use perl5301delta to Audit a Perl 5.30.1 Upgrade

You will finish with a short, evidence-based upgrade check for Perl 5.30.1: identify the release boundary, map its fixes to code you actually run, and record the interpreter and core module versions on this machine. Allow about 20 minutes for a small application, or longer if you need to run its full test suite. The examples are read-only unless you deliberately run your own tests.

This guide is about the perl5301delta release note, not a way to install Perl. The installed manpage describes differences between Perl 5.30.0 and 5.30.1. It is therefore useful when checking that particular maintenance upgrade, but it is not a complete migration guide from an older major or minor release.

1. Establish which Perl you are checking

Start by recording the interpreter selected by your shell:

$ command -v perl
/usr/bin/perl
$ perl -e 'print "$^V\n"'
v5.38.2

Your output may differ. On this host, the perl-doc package is version 5.38.2-3.2ubuntu0.6, and the installed perl5301delta manpage is generated from the Perl 5.38.2 documentation set. That does not mean this interpreter is Perl 5.30.1. It means the historical 5.30.1 release note is installed alongside a newer interpreter.

Checkpoint: if you expected Perl 5.30.1 but the version command reports something else, stop the audit here. Find the intended interpreter in the service unit, container image, virtual environment or deployment wrapper, then run the remaining commands through that path. Do not infer a service's Perl version from your interactive shell.

2. Set the release boundary

Read the note as a delta from 5.30.0 to 5.30.1. It says that there are no intentionally incompatible changes. That is reassuring for a maintenance release, but it is not a promise that every program will behave identically: a bug fix can expose code that depended on broken behaviour.

If you are coming from 5.28.0 or another earlier release, read the corresponding earlier delta documents as well. The 5.30.1 note explicitly points to perl5300delta for the changes between 5.28.0 and 5.30.0. Treating 5.30.1 as the entire upgrade plan is a common distraction trap, particularly when an old production host has skipped several releases.

3. Match the fixes to real code

Prioritise the items that can affect execution, memory use or build reliability. The release note lists six selected bug fixes:

• Setting $) now properly sets supplementary group IDs when the process has the required privileges.
• readline @foo now evaluates @foo in scalar context, avoiding the old stack-handling problem.
• sv_gets() recovers better when a signal handler modifies its target scalar.
• A regular expression containing Unicode literals no longer leaks an SV on each attempt when matching a non-UTF-8 string.
• sprintf with a negative precision for the hexadecimal floating-point conversion no longer takes the buffer-overflow path described in the note.
• scalar() on a reference no longer causes the reported assertion failure during compilation.

Search your source and tests for the relevant constructs, then write down whether each match is exercised in production. A search is triage, not proof. For example:

rg -n '\$\)|readline\s+@|sv_gets|sprintf\s*\(.*%\.\*a|scalar\s*\(' /path/to/project

Replace /path/to/project with a real checkout. Keep the search results as an audit note rather than changing code merely to make the list empty. The release note does not say that every use of these constructs is wrong.

4. Check the bundled module inventory

One bundled module changed in 5.30.1: Module::CoreList moved from version 5.20190522 to 5.20191110. Ask the interpreter you are auditing which version it exposes:

$ perl -MModule::CoreList -e 'print "$Module::CoreList::VERSION\n"'
5.20231129

The number above is this host's result, not an expected 5.30.1 result. A newer Perl can contain a newer CoreList, so do not use this command to prove that Perl 5.30.1 is installed. Use it to capture the local dependency state and to detect an unexpected interpreter in a deployment.

The same distinction applies to the documentation change about GitHub becoming the canonical repository and documenting pull requests. That is useful project information, not a runtime compatibility change.

5. Run focused tests before the full suite

Turn any relevant search result into a small regression test in a disposable branch or working copy. Run it with the exact Perl binary used by the application. A normal project test command is preferable because it includes the project's loading and environment assumptions:

cd /path/to/project
prove -l t/relevant-test.t

If the project has no focused test, run its documented test command instead. Do not copy a made-up expected output into a deployment record. A passing test means only that this invocation passed; record the command, Perl version and exit status together.

Pay particular attention to tests involving supplementary groups, signals, Unicode matching, formatted numeric output and compilation of reference expressions. The Win32 locale correction in the release note is platform-specific, so it is relevant to Windows test hosts rather than a reason to alter a Linux service.

6. Check build and platform notes

The release defines the ECHO macro used by a dtrace rule. The note explains that this repaired a Solaris build failure because Solaris make does not predefine the macro, while FreeBSD make apparently does. If you build Perl on Solaris, include a clean build in your acceptance evidence. On Linux, this particular note is unlikely to explain an application test failure.

The Win32 change makes locale names decode as UTF-8 in the affected path. If your test matrix includes Windows, exercise locale tests with the same code-page conditions as production. Do not generalise this platform note into a Linux configuration change.

7. Record failures without sending secrets

If a focused test fails, preserve the minimal reproduction and the output needed to diagnose it. For an actual Perl bug, the manpage points to perlbug and asks for a small test case plus perl -V. Treat bug reports as security-sensitive: inspect output for credentials, private paths and customer data before sending anything. Do not run perlthanks as part of an automated audit; it sends email.

There is no rollback operation in perl5301delta. If an upgrade changes service behaviour, use your package or deployment system's documented rollback to restore the previous interpreter, then rerun the focused test under both versions. Do not replace a system Perl by hand or delete the active interpreter while services are running.