/
README
96 lines (73 loc) · 4.11 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
NAME
README for Perl library Perl5-Dist-Backcompat
USAGE
Use perldoc to read documentation for module Perl5::Dist::Backcompat and
executable program p5-dist-backcompat.
DESCRIPTION
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.
Terminology
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.
Distribution/Distro
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.
CPAN Viability
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 <https://www.cpantesters.org> against older versions of
perl?
If such a release required a lot of fine-tuning in order to get "PASS"es
on CPANtesters, then we would say it has *low* direct CPAN viability.
If such a release required little fine-tuning to get those "PASS"es,
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.
Makefile.PL Status
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.