Use perlpolicy to Plan Safer Perl Upgrades

Somebody asks whether it is safe to upgrade Perl, and perlpolicy is where you find out instead of guessing. You will build a repeatable way to inspect the Perl policy installed on a Linux host, decide whether an upgrade sits on a stable or development track, and classify proposed maintenance changes before they reach production. The examples use Perl 5.38.2 and perl-doc 5.38.2-3.2ubuntu0.6, as installed on this system.

Allow about fifteen minutes. You need a shell and the perl-doc package. The checks are read-only and need no elevated privileges: nothing here edits Perl, changes a package source, or restarts a service.

1. Confirm the Perl and documentation versions

Start by recording the interpreter and package versions, so a policy statement from one host does not get mistaken for the policy or support status of another:

$ perl -v | sed -n '1,8p'
This is perl 5, version 38, subversion 2 (v5.38.2) built for x86_64-linux-gnu-thread-multi

$ 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

Your architecture and distribution revision may differ. The version inside perl -v is the one that matters for language compatibility, while the package revision just tells you which distribution build supplied the documentation.

2. Read the policy without losing your place

perlpolicy is a policy document, not a command with switches that change Perl. Open it in the terminal and search by section instead of reading it top to bottom:

$ man perlpolicy
$ man -P cat perlpolicy | less

The sections worth your time on an upgrade review are:

• GOVERNANCE explains who makes decisions for the Perl core.
• MAINTENANCE AND SUPPORT describes the support commitments recorded by that release of the document.
• BACKWARD COMPATIBILITY AND DEPRECATION defines how experimental, deprecated, discouraged and removed features should be treated.
• MAINTENANCE BRANCHES separates suitable fixes from changes that belong in a new stable series.

Once less is open, type /MAINTENANCE AND SUPPORT and press Enter, then n for the next match and q to return to the shell. That one habit saves you scrolling through governance material when the actual question was about a security update.

3. Treat support text as versioned evidence

The installed Perl 5.38.2 document says the two most recent stable release series are officially supported, that critical security releases may be provided for a major version whose 5.x.0 release is within three years, and that development releases get no security updates or bug fixes at all. It even gives a dated example: at the release of 5.36.0, 5.32.x was no longer officially supported apart from security updates.

Those sentences describe the policy recorded in this installed document at the time it was generated, not a live promise that 5.38.2 is supported today. Check the installed version first, then check the current upstream policy before making a lifecycle decision:

$ perl -v | grep -o 'v[0-9][^)]*' | head -n 1
v5.38.2

Current upstream documentation may show a newer support table and different release series. The official Perl 5.44.0 perlpolicy documentation records the support tracks for that release. Use it for upstream context, but use your distribution's own security support policy for the packages you actually deploy, since a vendor may backport a fix after upstream support has changed, or stop shipping a series sooner than upstream did.

4. Classify the release track before upgrading

Perl's versioning convention makes the middle component genuinely useful. Even-numbered series such as 5.38 and 5.40 are stable release series. Odd-numbered series such as 5.39 and 5.41 are development series leading to the next stable release. The final component is just the maintenance release number within a stable series.

How to read a Perl version:

Do not pick an odd-numbered series for a production host just because its number is higher. A development interpreter is useful for testing upcoming compatibility, but the policy document makes no promise of normal security or bug-fix support for it.

5. Review compatibility and deprecation risk

Read the terminology under BACKWARD COMPATIBILITY AND DEPRECATION whenever a test fails after an interpreter upgrade, because the labels are not interchangeable:

• Experimental means behaviour may change, be deprecated or be removed without notice. Isolate it behind tests and never fold it into a compatibility promise.
• Deprecated means removal is possible. The policy generally expects warnings for two release cycles, though a shorter path can be used when the risk is low or the benefit is high.
• Discouraged flags a construct considered a mistake, but does not currently make it a removal candidate.
• Removed means a feature, construct or module no longer ships in the Perl core, though a removed module may still be available from CPAN.

For a real upgrade, run the existing test suite with warnings enabled and log deprecation warnings as work items. Do not silence a warning just to make the upgrade look green. If a module was removed from core, decide deliberately whether a maintained dependency belongs in the application's dependency lockfile.

6. Decide whether a patch belongs in maintenance

Use MAINTENANCE BRANCHES to review a proposed backport or vendor patch. Acceptable categories include security fixes, crashes and memory corruption that do not change functionality, regressions, serious build or installation problems, portability fixes and minimal platform test fixes. Documentation corrections can qualify too.

The same section rejects changes that break binary compatibility, add or remove features, add new warnings or errors, deprecate features, or pull a new version of a dual-life module into a maintenance branch. A patch that looks small can still be the wrong patch for a maintenance release if it quietly changes the language contract.

For a proposed backport, capture the decision in a review record:

$ cat > /tmp/perl-maintenance-review.txt <<'EOF'
Perl: 5.38.2
Change: REPLACE_WITH_PATCH_OR_ADVISORY_ID
Reason: security fix, regression, or other documented category
Compatibility risk: REPLACE_WITH_TEST_RESULT
Decision: backport only if binary compatibility and branch rules remain intact
EOF
$ sed -n '1,6p' /tmp/perl-maintenance-review.txt

This creates a temporary review note only. Remove it afterwards with rm /tmp/perl-maintenance-review.txt if it holds nothing worth keeping, and never copy secrets or private vulnerability details into a shared temporary directory.

7. Use the policy when a decision is disputed

perlpolicy is a framework for decisions, not a substitute for a release note, security advisory or distribution support contract. When people disagree about an upgrade, cite the exact local section and version, then check the relevant perldelta document and your operating system's own security notices. For an urgent vulnerability, follow the security reporting process the Perl documentation describes rather than posting sensitive details to a public issue.