Use perlpolicy to Plan Safer Perl Upgrades

You will finish with a repeatable way to inspect the Perl policy installed on a Linux host, decide whether an upgrade is 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 do not need elevated privileges. You will not edit Perl, change a package source, or restart a service.

1. Confirm the Perl and documentation versions

Start by recording the interpreter and package versions. This prevents a policy statement from one host being 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 when you interpret language compatibility. The package revision 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:

$ man perlpolicy
$ man -P cat perlpolicy | less

The useful sections for 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.

When less is open, type /MAINTENANCE AND SUPPORT and press Enter. Use n for the next match. Press q to return to the shell. This small habit avoids scrolling through the governance material when the question is about a security update.

3. Treat support text as versioned evidence

The installed Perl 5.38.2 document says that 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 do not receive security updates or bug fixes. It also contains 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. They are 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 have 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 current upstream context, but use your distribution's security support policy for the packages you actually deploy. A vendor may backport a fix after upstream support has changed, or stop shipping a series sooner.

4. Classify the release track before upgrading

Perl's versioning convention makes the middle component 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 the maintenance release number within a stable series.

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

5. Review compatibility and deprecation risk

Read the terminology under BACKWARD COMPATIBILITY AND DEPRECATION when a test fails after an interpreter upgrade. The labels are not interchangeable:

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

For a real upgrade, run the existing test suite with warnings enabled and record deprecation warnings as work items. Do not silence a warning merely to make the upgrade green. If a module was removed from core, decide deliberately whether a maintained dependency can be added to 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 alter functionality, regressions, serious build or installation problems, portability fixes and minimal platform test fixes. Documentation corrections can also qualify.

The same section rejects changes that break binary compatibility, add or remove features, add new warnings or errors, deprecate features, or import 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 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 after the review with rm /tmp/perl-maintenance-review.txt if it contains no record you need to retain. 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. If people disagree about an upgrade, cite the exact local section and version, then check the relevant perldelta document and your operating system's security notices. For an urgent vulnerability, follow the security reporting process described by the Perl documentation rather than posting sensitive details to a public issue.

Do not change production Perl during this reading exercise. If an upgrade is approved later, take a package-manager snapshot or other rollback measure first, test the application, and schedule any service restart separately. Recovery depends on your package manager, so do not invent an undo command from this guide.