Turn perl5202delta(1) into a Safe Upgrade Review

A patch release sounds harmless until it quietly changes how Data::Dumper handles a deeply nested structure your logging depends on. perl5202delta(1) is where that kind of change gets written down, and this guide turns it into a small, repeatable review: 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 your test suite needs.

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 just because the manual page is present. The installed interpreter here is Perl 5.38.2, so examples reporting 5.38.2 are expected and correct.

1. Confirm the document and the interpreter

Start with read-only checks that 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

That last line is the interpreter version, not the version described by the manual. Pull up the release notes directly when you need the full local text:

$ man perl5202delta

2. Read the release boundary before changing code

The document covers the gap between 5.20.1 and 5.20.2. Starting from 5.20.0 instead? Read perl5201delta too, because this page deliberately skips that earlier transition. The notes say no changes were intentionally incompatible with 5.20.1, which is useful context but no substitute for testing your own application.

Spend your first pass on sections that can affect a running program: updated modules and pragmata, selected bug fixes, diagnostics, platform support, known problems, and 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 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, with a practical checkpoint list something like "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 against the interpreter that will actually run the application; this command prints the versions currently present:

$ 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 on an actual 5.20.2 installation. The local release notes say Data::Dumper moved from 2.151 to 2.151_01, adding a setting to limit recursion when dumping deeply nested data. Do not guess 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 any module whose behaviour matters to you. A version comparison alone does not prove compatibility, and a module's own 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, and save the exact command and result in the upgrade record. For a project using the standard Perl test layout, that typically looks like:

$ 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

Those filenames and counts are examples, not guaranteed output; use your project's documented test command if it has one. Add a small regression test for each relevant release-note item before upgrading. Exercise the code that serialises deep structures if you rely 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. Treat those as reasons to run tests that compile and execute the affected constructs, not as an invitation 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 your main upgrade tests pass. The local document says that lexical subroutines cannot be used as the SUBNAME argument to sort in this release. Relying on that form? Keep the existing workaround and add a test documenting the constraint.

Platform notes only matter where the application actually runs. Perl 5.20.2 records that IRIX and Tru64 work again, though some make test failures remain; it also lists an AIX socket fix and a Win32 child pseudo-process fix. Do not stretch those statements into a general claim of equal platform support everywhere. Run the relevant platform's own test suite and record its failures separately from application failures.

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 need 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, and 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

Bad result? Restore the previous interpreter or select it explicitly for the application, then rerun the baseline tests, keeping the failed test output with the change record. A release-note item may well explain a changed result, but never silence a failing test without understanding it first.

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. That command 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.