Semantic versioning may cause downstream problems in Perl core distribution

[jkeenan]

In the course of reviewing your response to #27 and the ancestor ticket in the Perl core distribution, Perl/perl5#22062, I had occasion to download the main branch of the podlators repository and update my local checkout. I ran the code through the customary perl Makefile.PL && make && make test sequence, then called make dist. I was surprised that the last command created a tarball named podlators-v6.0.0.tar.gz.

By calling git diff -w release/5.01..HEAD, I see that in the as-yet-unreleased version 6.0.0 you are moving to "semantic versioning." Further, by using git blame I can see that at least one relevant commit in this movement was:

commit 5576f199e15a12941ba3123836a92278de4f0151
Author:     Russ Allbery <rra@cpan.org>
AuthorDate: Fri Mar 15 22:34:25 2024 -0700
Commit:     Russ Allbery <rra@cpan.org>
CommitDate: Fri Mar 15 22:34:25 2024 -0700

    Update rra-c-util code and minimum Perl version
    
    Update test support libraries and scripts from the forthcoming
    rra-c-util 11.0.0 release. This now depends on Perl 5.12 or later,
    so update all of podlators to use that same minimum version.
    Switch to semantic versioning and the way of declaring package
    versions that is supported as of Perl 5.12.
    
    Enabling Perl 5.12 features requires rewriting one of the regexes
    in Pod::Man to not strip Unicode spaces such as non-breaking spaces.

I have heard of semantic versioning but have never used it myself and have no strong opinion about it, in general.

However, I would like to raise a yellow Caution flag about this with respect to the fact that podlators is distributed with the Perl core distribution. The most recent version is 5.01, and that version number is derived, per instruction in cpan/podlators/Makefile.PL, from cpan/podlators/lib/Pod/Man.pm. This version number is currently consistent with the way the $VERSION numbers of all other .pm files shipped with the Perl core are expressed, i.e.,, as \d+\.\d+(_\d+)? 2-part decimal numbers (with possible _ to indicate a divergence from the CPAN version). A command like this:

grep DISTRIBUTION Porting/Maintainers.pl | sed -e "s/\.tar\.gz',//" | sed -e 's/^.*-//' | sort

... will give you a feel for how these version numbers are spelled.

In 6.0.0, your Makefile.PL now has a subroutine dist_version which returns a string which starts with a v and has 3 decimal parts rather than just 2. In the core distribution we have a number of programs under Porting/ which are tooling to, inter alia, identify CPAN distributions which have a different $VERSION on CPAN from that found in the core; and "synch" a more recent version of a distribution from CPAN into core. I am one of the Perl committers who typically runs these programs before a development or production release.

My hunch is that the first time one of these Porting/ programs sees podlators-v6.0.0, it will gag and have to be rewritten. I am not sure whether such a program will gag on the v, on the 3-decimal parts, or on the combination of both. I believe that a

While I am sure that you have probably spent some time pondering this and I know that N.N.N distributions exist on CPAN -- though I'm not sure yet as to vN.N.N distributions -- I'd like to ask if you really need to move away from N.N versioning. Moving to vN.N.N. is definitely going to lead to a long yackfest on P5P and several hours of work for core committers.

Thank you very much.
Jim Keenan

[rra]

Thanks, in retrospect I should have realized I needed to raise this as well once I realized that all the Perl tooling wants to copy the v into the distribution name (and that appears to be the practice on CPAN as well for modules using v-strings as versions).

I'll raise this on P5P and start the yackfest. I would really like to standardize on semantic versioning for all the software I maintain, and am willing to submit PRs to Perl to fix the scripts.

[jkeenan]

Thanks, in retrospect I should have realized I needed to raise this as well once I realized that all the Perl tooling wants to copy the v into the distribution name (and that appears to be the practice on CPAN as well for modules using v-strings as versions.

I'll raise this on P5P and start the yackfest. I would really like to standardize on semantic versioning for all the software I maintain, and am willing to submit PRs to Perl to fix the scripts.

I just ran minicpan and can now state that there are many distros with vN.N.N version numbers in their names. But I can't recall seeing that pattern in Perl 5 core in the 12 years I've been working on it. I'm trying to think of a way to simulate the workings of those programs.

[haarg]

I don't really see this as something that has to be preemptively fixed. If there are problems with things like the sync-with-cpan or core-cpan-diff scripts, they will be trivial to fix. And that can happen after there is a release to work with.

[jkeenan]

Ongoing discussion in perl core: Perl/perl5#22101

[jkeenan]

Ongoing discussion in perl core: Perl/perl5#22101

Since I've green-lit the patch found in the core pull request cited above, this ticket is moot. Thanks.