README for Perl library Perl5-Dist-Backcompat

Use perldoc to read documentation for module Perl5::Dist::Backcompat and executable program p5-dist-backcompat.

As of January 2022, there are 41 distributions (hereinafter, "distros") underneath dist/ in the Perl 5 core distribution. By definition, all of these are maintained by Perl 5 Porters in core but are potentially releasable to CPAN so that they may be installed against older perl releases. (To date, all but one of those 41 distros has had at least one CPAN release in the past.)

But if were to release the code in a given dist/ distro to CPAN today, would it build and test correctly against older perls? Which older perls? More to the point, suppose that we've made changes to the code in these distros in core since the last production release of perl? If we were to release that code to CPAN, would that code fail against older versions of perl?

This program, p5-dist-backcompat, tries to answer those questions. It aims to be a P5P core development tool which, when run in advance of a development, production or maintenance release of perl, can alert a release manager or core developer to potential problems as described above.

Every one of the dist/ distros has its own history, quirks and coding challenges. So within this program we will use certain terminology to group distros that share certain characteristics.

These terms will be used in two senses:

• In Perl 5 Core Distribution

  A directory tree underneath dist/ in the Perl 5 core distribution. If the directory has a multipart name, it is spelled Some-Distro (as distinct from the Some::Distro spelling used for packages or modules within that distribution.

• CPAN Release

  A release to CPAN of code from a given distro within the core distribution.

Setting aside metadata files like META.json, META.yml and Changes, if we were to take the code for a given dist/ distro as it stands today, added a Makefile.PL as needed (see next section), rolled it up into a tarball and uploaded that tarball to CPAN, how would that CPAN release fare on CPANtesters against older versions of perl?

If such a release required a lot of fine-tuning in order to get PASSes on CPANtesters, then we would say it has low direct CPAN viability.

If such a release required little fine-tuning to get those PASSes, then we would say it has high direct CPAN viability.

The CPAN release version of a distro may need fine-tuning for reasons such as:

• To work with changes in Perl syntax over the years.
• To install prerequisites not available in older versions of perl.
• To hold test files not needed within the core distribution, such as author-only tests to be run by the person doing the CPAN release.

When any of these dist/ distros gets a CPAN release, it needs to have a Makefile.PL so that ExtUtils::MakeMaker can generated a Makefile. The Makefile is in turn run by make. But that doesn't mean that a given dist/ distro has a Makefile.PL of its own within the core distribution. As of today we can classify these distros according to the following statuses:

• unreleased

  This kind of dist/ distro has apparently never had a CPAN release, so it has never needed a Makefile.PL for that purpose and doesn't have one in core. p5-dist-backcompat ignores such distros; as of date there is only 1 such distro.

• cpan

  This kind of dist/ distro may or may not have a Makefile.PL of its own in the core distribution -- neither native nor generated. Hence, when released to CPAN, the CPAN maintainer has to provide an appropriately coded Makefile.PL as part of the tarball. The current version of this program, p5-dist-backcompat, always uses the CPAN version of a distro's Makefile.PL.