Semantic versioning in dual-life modules

[Russ Allbery]

Hello everyone,

I'm trying to adopt semantic versioning across all the software packages I
maintain, rather than remembering and juggling several package-specific ad
hoc versioning schemes. This includes the dual-life module distributions
podlators and Term::ANSIColor.

I don't care about the pre-release or build metadata parts of a semantic
version, thankfully, so the Perl language provides good native support for
translating a semantic version into a module version with:

package Pod::Man v6.0.0;

and related variations.

I was assuming that this would translate into a distribution tarball of
podlators-6.0.0.tar.gz. podlators had used versions like that in the
distribution tarball between 2006 and 2013, before I switched away from
semantic versions as part of unifying the distribution version and all of
the module versions rather than letting them all vary independently. (At
the time, v-string support was somewhat more experimental and I was still
supporting versions of Perl that didn't support the new package syntax.)

However, it turns out this is not the case: CPAN::Meta::Spec specifically
requires the v prefix.

Dotted-integer (also known as dotted-decimal) versions consist of
positive integers separated by full stop characters (i.e. "dots",
"periods" or "decimal points"). This are equivalent in format to Perl
"v-strings", with some additional restrictions on form. They must be
given in "normal" form, which has a leading "v" character and at least
three integer components.

Therefore, my understanding is that if I move forward with both semantic
versions and ensuring the module version matches the META.json version and
the version in the tarball, the release would be podlators-v6.0.0.tar.gz
with a META.json version key of v6.0.0 (and likewise for the version keys
for each module in provides). There are some distributions already on
CPAN with versions like that.

James Keenan pointed out in https://github.com/rra/podlators/issues/29
that this is likely to pose problems for the core maintenance scripts. I
can see a couple of problems at least in sync-with-cpan at a glance.

Does anyone see a flaw in my analysis?

If not, I still would like to move forward with semantic versions, and am
willing to volunteer some time to try to fix the core scripts to work
correctly with such versions. I haven't ever worked on core before,
though, so alas my volunteer effort will probably not be zero effort for
all of you, and thus you are certainly entitled to say no, this is just
not something we can support for core modules.

I think new releases of podlators and Term::ANSIColor have missed the
window for 5.40 already, which in the light of this is probably good
timing, so this is not urgent, assuming I won't break the world by even
putting them on CPAN.

[Russ Allbery]

Post by Russ Allbery
Therefore, my understanding is that if I move forward with both semantic
versions and ensuring the module version matches the META.json version
and the version in the tarball, the release would be
podlators-v6.0.0.tar.gz with a META.json version key of v6.0.0 (and
likewise for the version keys for each module in provides). There are
some distributions already on CPAN with versions like that.
James Keenan pointed out in https://github.com/rra/podlators/issues/29
that this is likely to pose problems for the core maintenance scripts.
I can see a couple of problems at least in sync-with-cpan at a glance.

To close the loop on this on the mailing list, Graham Knop fixed several
issues with the Porting scripts at [1] (thank you!), and the consensus on
that discussion seemed to be that any subsequent issues could be sorted
out as they happened.

[1] https://github.com/Perl/perl5/pull/22101

I therefore intend to move forward with this new versioning scheme for
podlators and Term::ANSIColor, but please let me know if there are any
concerns or if there are any problems that I can help with.