Use perl5220delta as a Perl Upgrade Checklist

perl5220delta(1) decides whether jumping two major Perl versions at once is a quiet non-event or a source of new bugs. This guide turns it into a short upgrade check: identify the Perl release the document describes, compare its changes with the interpreter installed on this machine, and run small tests for syntax or behaviour that matters to your code. Allow about fifteen minutes for a first pass, longer if you need to review a large codebase.

You need a shell, the perl-doc package, and a Perl installation. The examples are read-only, create no files, and need no root. They use the installed Ubuntu package version perl-doc 5.38.2-3.2ubuntu0.6, whose manual page is generated for Perl v5.38.2 but documents the historical 5.22.0 release.

1. Confirm the document and interpreter versions

Start with the manual page itself, a reference document rather than a command that applies an upgrade:

$ man perl5220delta
PERL5220DELTA(1)       Perl Programmers Reference Guide       PERL5220DELTA(1)

The page describes differences between Perl 5.20.0 and Perl 5.22.0. It says nothing about every change in the Perl actually installed today, so record the interpreter version separately:

$ perl -e 'print "$^V\n"'
v5.38.2

2. Find the change categories that affect your code

Read the headings before copying examples. The useful groups are core enhancements, security, incompatible changes, modules and pragmata, utility changes, configuration and compilation, platform support, selected bug fixes, and performance enhancements.

For an ordinary application review, start with Incompatible Changes. The 5.22 notes include stricter handling of several old constructs, including importing functions from UNIVERSAL, omitting @ or % on array and hash names, and some regular-expression syntax. Then check Core Enhancements for features you might choose to use, and Modules and Pragmata if your dependency versions are tied to the Perl core.

Do not quietly turn an experimental feature into a project requirement. The page labels bitwise operators, reference aliasing, use re 'strict', and some regular-expression constructs as experimental or subject to change. That label is a compatibility warning, not a recommendation to switch everything on.

3. Test the new bitwise operator mode

Perl 5.22 added an experimental bitwise feature. In that mode, the ordinary operators behave consistently as numeric operators, and the dotted operators behave consistently as string operators. Enable the feature explicitly and silence only its named experimental warning category:

$ perl -e 'use feature "bitwise"; no warnings "experimental::bitwise"; my $n = 6 & 3; my $s = "101" &. "001"; print "$n $s\n"'
2 001

The output is a deliberately small check: numeric 6 & 3 gives 2, while the string operation combines the characters position by position. Keep this test in a temporary compatibility branch until you know which Perl versions your application needs to support.

Common trap: the punctuation is significant. &., |., ^. and ~. are different operators from their undotted forms. If your shell or editor makes these hard to spot, put the test in a real Perl file and run it with perl file.pl.

4. Check input handling with the double diamond

The new <<>> operator resembles the older diamond operator but opens each @ARGV item as a filename using three-argument open. A filename beginning with | is therefore treated as a filename, not a pipe command. Useful when input names come from outside the program, but it does not validate that a filename is trusted or that the file is safe to read.

$ perl -e 'while (<<>>) { print }' /etc/hostname
server.example.com

Your output will show your own machine's hostname, not necessarily the value above. The command only reads the file. Checkpoint: if the file does not exist, Perl reports an open error and the loop provides no normal input; test that failure deliberately in a disposable command before changing production code.

5. Exercise the regular-expression and number changes

The /n regular-expression modifier stops ordinary capturing groups from populating $1, $2, and so on, a handy way to document that a grouping exists only for precedence:

$ perl -e '"hello" =~ /(hi|hello)/n; print defined($1) ? "captured\n" : "not captured\n"'
not captured

Perl 5.22 also added hexadecimal floating-point literals and %a output:

$ perl -e 'printf "%a\n", 0x1.23p-4'
0x1.23p-4

These examples only verify that the installed interpreter accepts the syntax. They say nothing about whether a different build shares the same floating-point precision, locale behaviour, or Unicode data; run application-level tests for those concerns instead.

6. Compare core module versions before relying on them

The manual page names many module updates, but a distribution can package a different set of versions. Use corelist to compare the two historical Perl releases:

$ corelist --diff 5.20.0 5.22.0 | sed -n '1,8p'
App::Cpan                                 1.62       1.63
App::Prove                                3.30       3.35
App::Prove::State                         3.30       3.35
App::Prove::State::Result                 3.30       3.35
App::Prove::State::Result::Test           3.30       3.35
Archive::Tar                              1.96       2.04
Archive::Tar::Constant                    1.96       2.04
Archive::Tar::File                         1.96       2.04

The exact list depends on the installed corelist data, so treat it as an inventory rather than a promise about your deployment. For a module your application imports, check its version directly with a harmless command such as perl -MArchive::Tar -e 'print $Archive::Tar::VERSION, "\n"'. Nothing here should be installed or upgraded as part of the review.

7. Turn findings into a controlled upgrade decision

Search your source for the incompatible constructs and experimental features you actually use. Run the application's existing test suite against the target interpreter, then repeat it with warnings enabled where the project permits that. Pay particular attention to regular expressions, locale-sensitive code, list slices, module loading, and code that relies on old error text.

The security notes in this document describe changes made in the 5.22 release, such as stronger stack protection when available and a fix in Safe. They are not a substitute for rebuilding Perl with your distribution's current security updates, and an old delta page never makes an end-of-life interpreter safe to deploy.

There is no undo command here because this guide changes no system state. A failing compatibility test should stay attached to its command and interpreter version in the issue or upgrade branch until you fix the code or dependency deliberately and rerun it. If an upgrade has already happened elsewhere, recovery means selecting the previously tested interpreter or package version through your normal deployment process.