Use perl5220delta as a Perl Upgrade Checklist

You will turn perl5220delta(1) 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 apart from creating no files, and do not need 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. This is a reference document, not 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 does not describe every change in the Perl installed today. Record the interpreter version separately:

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

Checkpoint: write down both versions. If your application is moving from 5.20 to 5.22, this page is directly relevant. If you are moving from another release, use the matching perl<old>delta and perl<new>delta pages as well. Do not treat a successful run on Perl 5.38 as proof that a 5.22 target behaves identically.

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 silently 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 enable everything.

3. Test the new bitwise operator mode

Perl 5.22 added an experimental bitwise feature. In that mode, the ordinary operators work consistently as numeric operators and dotted operators work 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 supports.

Common trap: the punctuation is significant. &., |., ^. and ~. are different operators from their undotted forms. If your shell or editor makes these hard to see, 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. That means a filename beginning with | is treated as a filename rather than a pipe command. This is 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.dixon.cx

Your output will contain your machine's hostname, not necessarily the value shown above. The command only reads the file. Checkpoint: if the file does not exist, Perl reports an open error and the loop does not provide 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 prevents ordinary capturing groups from populating $1, $2, and so on. It is a useful 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 verify that the installed interpreter accepts the syntax. They do not prove that a different build has the same floating-point precision, locale behaviour, or Unicode data. Run application-level tests for those concerns.

6. Compare core module versions before relying on them

The manual page names many module updates, but a distribution may 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 use 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"'. Do not install or upgrade anything as part of this 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 with 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.

Security notes in this document describe changes 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. Never infer that an old delta page makes an end-of-life interpreter safe to deploy.

There is no undo command because this guide changes no system state. If a compatibility test fails, keep the failing command and its interpreter version in the issue or upgrade branch, correct the code or dependency deliberately, and rerun the test. If an upgrade has already been attempted elsewhere, recovery means selecting the previously tested interpreter or package version through your normal deployment process.