Use perl5202delta as a Safe Perl 5.20.2 Upgrade Checklist

You will turn perl5202delta(1) into a small, repeatable review for a Perl 5.20.2 upgrade: record the runtime you actually have, identify code affected by the release notes, run focused tests, and keep the change reversible. Allow about 20 minutes for a first pass, plus the time needed by your test suite. The guide uses the locally installed perl-doc package, version 5.38.2-3.2ubuntu0.6, whose copy of this historical document describes the change from Perl 5.20.1 to Perl 5.20.2.

This is a release-notes workflow, not an installation procedure. Do not infer that the machine is running Perl 5.20.2 from the presence of the manual page. The installed interpreter here is Perl 5.38.2, so examples that report 5.38.2 are expected.

1. Confirm the document and the interpreter

Start with read-only checks. They need no elevated privileges and establish which files and binary you are reviewing:

$ command -v perl
/usr/bin/perl
$ dpkg-query -W -f='${Package} ${Version}\n' perl-doc
perl-doc 5.38.2-3.2ubuntu0.6
$ perl -e 'printf "%vd\n", $^V'
5.38.2

The last line is the interpreter version, not the version described by the manual. Check the release notes directly when you need the complete local text:

$ man perl5202delta

Checkpoint: you should be able to state both versions in your change notes. If you need to deploy Perl 5.20.2 itself, stop here and follow your platform's packaging or build process. This page does not tell you to replace the system interpreter.

2. Read the release boundary before changing code

The document covers the difference between 5.20.1 and 5.20.2. If your starting point is 5.20.0, read perl5201delta as well, because this page deliberately does not repeat that earlier transition. The notes say that no changes were intentionally incompatible with 5.20.1. That is useful context, but it is not a substitute for testing your application.

Focus your first pass on the sections that can affect a running program: updated modules and pragmata, selected bug fixes, diagnostics, platform support, known problems, and the errata from earlier releases. The notes also record documentation-only changes, such as the newly documented postderef feature and the new perlunicook document. Treat those as useful pointers rather than changes you must install separately.

Do not copy every bullet into a ticket. Record only the items that intersect your code, platform, or test coverage. A practical checkpoint is a short list such as "Data::Dumper output", "locale-sensitive regular expressions", "AIX socket code", or "lexical subs passed to sort".

3. Compare core module versions in the target environment

The release notes name version changes for several core modules. Compare those names with the interpreter that will run the application. This command prints versions for modules that are present in the current installation:

$ perl -MData::Dumper -MIO::Socket -MModule::CoreList -MStorable -e 'printf "Data::Dumper %s\nIO::Socket %s\nModule::CoreList %s\nStorable %s\n", $Data::Dumper::VERSION, $IO::Socket::VERSION, $Module::CoreList::VERSION, $Storable::VERSION'
Data::Dumper 2.188
IO::Socket 1.52
Module::CoreList 5.20231129
Storable 3.32

Your output will differ if you are testing a Perl 5.20.2 installation. The local release notes say that Data::Dumper moved from 2.151 to 2.151_01 and that the update added a setting to limit recursion when dumping deeply nested data. Do not invent the setting's spelling from memory. Read the installed Data::Dumper documentation in the target environment before adding it to a program:

$ perldoc Data::Dumper
$ perldoc -f Dumper

Use the same approach for a module whose behaviour matters to you. A version comparison alone does not prove compatibility, and a module's documentation can be newer than the release note you started from.

4. Turn relevant fixes into focused tests

Run the application's existing test command before changing the Perl runtime. Save the exact command and result in the upgrade record. For a project using the standard Perl test layout, a typical command is:

$ prove -lr t
t/00-load.t .... ok
t/10-basic.t ... ok
All tests successful.
Files=2, Tests=12,  1 wallclock secs
Result: PASS

The filenames and counts are examples, not guaranteed output. Use the project's documented test command if it has one. Add a small regression test for each relevant release-note item before upgrading. For example, exercise the code that serialises deep structures if you depend on safe diagnostic dumps, and exercise UTF-8 regular expressions if your application handles non-ASCII text.

The release notes also identify fixes for crashes, memory corruption, infinite compilation loops, and regular-expression failures. Those entries are reasons to run tests that compile and execute the affected constructs, not reasons to reproduce a crash deliberately. Keep malformed-input tests bounded and run them in a disposable test environment.

5. Check known problems and platform limits

Read the Known Problems section even when the main upgrade tests pass. The local document says that lexical subroutines cannot be used as the SUBNAME argument to sort in this release. If your code relies on that form, preserve the existing workaround and add a test that documents the constraint.

Platform notes matter only where the application runs. Perl 5.20.2 records that IRIX and Tru64 work again, while some make test failures remain. It also lists an AIX socket fix and a Win32 child pseudo-process fix. Do not turn those statements into a general claim that every platform is equally supported. Run the relevant platform's own test suite and record failures separately from application failures.

Checkpoint: your review should now have three statuses for each relevant item: tested and passing, tested and failing, or not applicable. "Not applicable" should include a reason, such as a platform or feature your program does not use.

6. Apply the runtime change with a rollback plan

Only after the baseline and focused tests are recorded should you change the interpreter used by the application. This may require elevated privileges or a service change, depending on how Perl is installed. Stop the service and back up configuration only according to your normal change procedure. Do not remove the working Perl binary or overwrite a shared system path as an experiment.

After the change, repeat the version and module checks, then run the same tests:

$ perl -e 'printf "%vd\n", $^V'
$ prove -lr t

If the result is bad, restore the previous interpreter or select it explicitly for the application, then rerun the baseline tests. Keep the failed test output with the change record. A release-note item may explain a changed result, but do not silence a failing test without understanding it.

7. Report a suspected core bug safely

The manual recommends reducing a suspected defect to a small test case and including perl -V in a bug report. Run that command locally; it is read-only but can expose build and platform details, so review the output before sharing it:

$ perl -V

Use the project's current reporting route for ordinary bugs. For a possible Perl security issue, do not paste exploit details into a public tracker. Follow the security contact guidance in the installed documentation and your organisation's disclosure policy.