Use perl588delta to Audit a Perl 5.8.8 Upgrade

You will finish with a small, evidence-based checklist for reviewing code that moved from Perl 5.8.7 to 5.8.8. The perl588delta page is release documentation, not a command that changes Perl or runs an upgrade. This guide uses the installed perl-doc package, which provides the manpage, and keeps the historical notes separate from the behaviour of your current interpreter.

Allow about fifteen minutes for a first pass. You need a shell, the perl-doc package, and a test copy of the application if you intend to run its test suite. The examples are read-only unless explicitly marked otherwise. No elevated privileges are required.

1. Confirm the interpreter and documentation versions

Start by recording what is actually installed. This prevents a common mistake: reading a 5.8.8 change list and assuming it describes the Perl that will run your program today.

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

Your version and package revision will differ. The useful checkpoint is that the interpreter and documentation package are identified, and that the first line says which Perl version the installed program reports.

On a system without Debian package metadata, use perl -V:version and record the package information from the operating system's normal package manager. Do not install an old Perl merely to make this page's examples match. Test a legacy application in an isolated environment if it genuinely needs Perl 5.8.8.

2. Read the release boundary before the details

Open the page directly and read its description first:

$ man perl588delta

The page describes differences between 5.8.7 and 5.8.8. It says that no changes were intentionally incompatible with 5.8.7, but that statement is about that release transition. It is not a promise that code written for 5.8.8 will behave unchanged on Perl 5.38.2, or that every old module remains available.

For a non-interactive copy of the text, use:

$ man -P cat perl588delta > perl588delta.txt
$ grep -n -E '^(Core Enhancements|Utility Changes|Selected Bug Fixes|New or Changed Diagnostics)' perl588delta.txt

This creates a local notes file. It is safe to remove after the review with rm perl588delta.txt; if you need to keep it, place it in your project review area rather than overwriting an existing file without checking it first.

3. Check the changes that can alter source behaviour

Read the short sections before scanning the long module list. The core change says that chdir, chmod and chown can accept filehandles when the operating system supplies the matching fchdir, fchmod or fchown call. That is conditional platform behaviour, not a guarantee for every Unix-like system.

The selected bug fixes are more useful as test prompts. Perl 5.8.8 corrected selective no warnings 'category' handling when warnings were enabled with -w. It also fixed particular sprintf bounds problems, debugger and Unicode slowdowns, several ithreads leaks, and the handling of three-argument open with the open pragma. Search your test suite for those features instead of assuming a general version bump is enough.

Keep the old and new behaviour in separate tests. For example, a warning test should assert the warning categories your application expects, while an I/O test should check the result of the open rather than matching a complete diagnostic string. Diagnostics can change wording between Perl releases.

4. Review utility changes without changing the system

The release notes also cover utilities shipped with Perl. In 5.8.8, h2xs gained --use-xsloader, and perlivp gained -a to run all its tests, including checks that are no longer part of its default run. Inspect the utilities installed on the host before copying an old command into a build script:

$ command -v h2xs perlivp
$ h2xs --help | grep -F -- '--use-xsloader'
$ perlivp --help | grep -E '(^|[[:space:]])-a([[:space:]]|,|$)'

A missing match is useful evidence: the current utility may not expose a historical option, or the utility may not be installed. Do not pass an option just because it appears in an old delta page. Check the installed help and the current utility manpage first.

5. Turn the notes into a compatibility test

Make one test entry for each feature your application uses. Include the Perl version, operating system, module versions, and the exact command used to run the test. The module list in perl588delta is a useful inventory: it records upgrades such as CGI, Encode, Storable, Time::HiRes and Unicode::Collate, but it does not install or select those versions for you.

Use the application's own test command in a disposable checkout. A simple version gate can establish which interpreter a test job used:

$ perl -e 'printf "perl=%s\n", $^V'
perl=v5.38.2
$ perl -MConfig -e 'print "$Config{archname}\n"'
 x86_64-linux-gnu-thread-multi

Do not compare a clean exit alone with the release notes. Check warnings, generated files, Unicode input, debugger runs, thread-heavy paths and error handling where those features matter. Preserve the old test result before changing code so a later failure is attributable.

6. Record the decision and stop at the right boundary

Your review is complete when you can say which interpreter ran the tests, which 5.8.8 notes apply, and which claims remain conditional on the operating system or module version. If the review finds a regression, keep the failing test and report the smallest reproducible case with perl -V, as the manpage requests. Do not send application data or credentials in a bug report.