Read Perl 5.8.2's Change Notes Without Guessing at Compatibility

You will finish with a small, repeatable audit for software moving between Perl 5.8.1 and 5.8.2: identify the installed documentation, check the interpreter you will actually run, find the cases that require rebuilding modules, and turn the release notes into tests for your application. The examples are read-only apart from a temporary demonstration file if you choose to create one.

Allow about 20 minutes. You need a shell and the perl-doc package. This guide uses the locally installed perl582delta(1) as its primary source. On this machine that package is perl-doc 5.38.2-3.2ubuntu0.6, so the document describes a historical Perl release even though the host's interpreter is Perl 5.38.2.

1. Confirm which documentation and interpreter you have

First check the package and interpreter. These ordinary, read-only commands do not need sudo:

$ dpkg-query -W -f='${Package} ${Version}\n' perl-doc perl-base
perl-doc 5.38.2-3.2ubuntu0.6
perl-base 5.38.2-3.2ubuntu0.6
$ perl -v
This is perl 5, version 38, subversion 2 (v5.38.2) built for x86_64-linux-gnu-thread-multi

Your version will differ. Do not read the 5.8.2 notes as proof that a current interpreter has the same implementation or bugs. They are a migration record for the change from 5.8.1 to 5.8.2.

Checkpoint: if dpkg-query reports that perl-doc is not installed, stop here or use the package source approved for your distribution. Do not substitute an unrelated release note.

2. Read the release boundary locally

Render the complete manual in the terminal:

$ man -P cat perl582delta | col -b | less

Search within less for /Incompatible Changes, /Hash Randomisation, /Threading, and /Platform Specific Problems. If you only need a captured copy for review, write it in a disposable directory, not in a source or deployment directory:

$ tmpdir=$(mktemp -d)
$ man -P cat perl582delta | col -b > "$tmpdir/perl582delta.txt"
$ sed -n '1,220p' "$tmpdir/perl582delta.txt"
$ rm -rf "$tmpdir"

The final command removes only the temporary directory named by mktemp. If you need to keep the notes, copy the file to a deliberately chosen review location instead. The manual's scope is explicit: it compares 5.8.1 with 5.8.2. For an upgrade from 5.6.x, read the earlier perl58delta and perl581delta documents as well.

3. Find the compatibility trap before starting an upgrade

The highest-risk item in these notes is narrow but operationally significant. Threaded Perl 5.8.1 builds lost binary compatibility with 5.8.0 for modules that called certain re-entrant system calls. Perl 5.8.2 restored compatibility with 5.8.0, which necessarily broke compatibility with 5.8.1 for that affected case.

If your old runtime is a threaded Perl 5.8.1 and it loads compiled modules, treat the upgrade as a rebuild event. Record the module list, install Perl 5.8.2 in the target environment, then recompile and reinstall those modules against that interpreter. Do not copy the old .so files into the new installation.

For a modern host, use the same principle even though the exact 5.8.1 boundary no longer applies. Check the interpreter and module ABI together:

$ perl -V:archname -V:version -V:useithreads
archname='x86_64-linux-gnu-thread-multi';
version='5.38.2';
useithreads='define';

Exact field formatting varies. The useful facts are the Perl version, architecture and whether threads are enabled. If any of those change, plan to rebuild XS modules rather than assuming an old binary is safe.

4. Test code that assumes a hash order

Perl hash key order is not an application interface. The 5.8.2 notes describe an amended hash-randomisation implementation that remained robust against algorithmic-complexity attacks while restoring source and binary compatibility with both 5.8.0 and 5.8.1 in the affected area.

The practical audit is to search application code and tests for output that serialises a hash and then compares the text byte-for-byte. A quick repository search is read-only:

$ rg -n 'keys\s*\(|values\s*\(|each\s*\(|Data::Dumper|sortkeys|hash' /path/to/project

Replace /path/to/project with a real checkout. When order matters for output, sort keys explicitly. With Data::Dumper, use its documented Sortkeys setting. When insertion order itself is the requirement, use a deliberately ordered data structure rather than relying on a normal hash.

Do not "fix" a failing test by pinning a hash seed. The older manual mentions PERL_HASH_SEED in its surrounding Perl documentation, but making a process appear deterministic can hide the ordering assumption you need to repair. Use a fixed seed only for a controlled diagnostic, never as the application design.

5. Check the smaller fixes that affect your platform

The release notes also record fixes for memory leaks involving variables shared between threads, parser handling of syntax errors involving unrecognised filetest operators, and more complete interpreter initialisation when -DMULTIPLICITY is off. These are useful clues for regression testing, not promises that every program will show a visible change.

If you build or embed Perl, read the platform section before choosing a test matrix. The 5.8.2 notes mention adjusted dynamic-linker flags for Solaris and OS X, fixes for OS/2 sockets and tmpfile, and workarounds for setreuid and related calls on OS X. A Linux host cannot validate those platform-specific fixes. Run the test on the target platform with the target build configuration.

The list of updated modules and pragmata includes Devel::PPPort, Digest::MD5, MIME::Base64, Time::HiRes, Unicode::Collate, Unicode::Normalize, UNIVERSAL and others. Treat that list as a prompt to compare your application's dependency lockfile and regression results, not as a reason to upgrade individual modules out of context.

6. Record evidence for the change review

Save the exact interpreter identity, the package versions, the release-note scope, and the result of the application's tests. A compact evidence block can be produced without elevated privileges:

$ printf 'perl: '
$ perl -e 'printf "%vd\n", $^V'
perl: 5.38.2
$ perl -V:archname -V:useithreads
archname='x86_64-linux-gnu-thread-multi';
useithreads='define';
$ man -P cat perl582delta | col -b | sed -n '1,35p'

Keep the output with the change record if your process requires it. If the upgrade fails, restore the previous runtime or environment snapshot, put the old module set back with its matching interpreter, and rerun the last known-good test suite. Do not mix modules from the failed and restored runtimes.