|
PUCKERING has asked for the wisdom of the Perl Monks concerning the following question:
I recently published a new module on CPAN, starting off with a vanilla version number of 1.00. Then as I was experimenting with Dist::Zilla I decided to go with a date based version scheme. Unfortunately, I messed it up. I uploaded a module with version v2022.08.30, which was acceptable to Dist::Zilla and CPAN but which I now think could create upward compatibility problems because I used the year where the Major version number should go. Now I can't use the Major version to handle interface changes, and it'll look like there's an interface change every time a new year comes along.
I want to ditch this tarball and replace it. But if I adopt a more sensible date-base versioning scheme, such as v1.22.242 (major version, year of century, day of year) then the prior version will look newer since it is v2022.
I've submitted a delete request on the tarball, but that will take a week to process. Probably by then the back-end machinery will build and test and release the thing. (It would be great if the pending delete stops that from happening -- if that is how it works, please let me know.)
Bottom line, I'm seeking is some insight into how PAUSE file deletions work, and whether there's anything else I can do to fix this mess or avoid making it worse. |
Re: Help with PAUSE mechanics - replacing a bad module
by eyepopslikeamosquito (Archbishop) on Aug 31, 2022 at 07:43 UTC
|
> I recently published a new module on CPAN, starting off with a vanilla version number of 1.00
Well done for not starting with 1.0.0. :)
CPAN versioning is something of a dark art, as I discovered when
attempting to offer some general CPAN Module Versioning advice at:
In that node, I advised starting at 0.01, 0.02, 0.03, ... and only when
you've finally produced a stable, production quality API, on which users have come to depend,
to indicate that by bumping the module version to 1.00.
At least that seems the most popular approach in the Perl community.
See that node's "CPAN Versioning Refs" section for why you should avoid a 1.2.3 versioning style.
> if I adopt a more sensible date-base versioning scheme, such as v1.22.242 (major version, year of century, day of year)
Why is this more sensible? Who endorses this scheme?
Which well-known CPAN modules use it?
Update: Re^2: Module version numbers best practice (meaning--) by tye cautions that using dates as version numbers runs into problems when trying to assign meaning to version numbers.
| [reply] |
|
|
I advised starting at 0.01, 0.02, 0.03, ... and only when you've finally produced a stable, production quality API, on which users have come to depend, to indicate that by bumping the module version to 1.00.
This is precisely and exactly what I do. Generally any release before 1.00 has a note in the DESCRIPTION that the public API may change. Once I know the outside API will no longer change, I've got as close to or 100% test coverage, and the documentation is fully complete, I remove the warning and stamp it as 1.00, or the first stable version.
Sometimes getting to 1.00 takes only a few version bumps, others have taken me a few dozen, all depending on the complexity of the distribution in question.
| [reply]
[d/l] |
Re: Help with PAUSE mechanics - replacing a bad module
by SankoR (Prior) on Aug 31, 2022 at 03:50 UTC
|
I'm sure this is explained somewhere on PAUSE but you only really had to reset the version for the packages inside the bad dist. The next time you upload a stable distribution, it'll be indexed as usual.
Edit: or manually schedule a reindex for your old 1.00 dist already on CPAN until you're ready to move on to v1.22.242, etc. | [reply] |
|
|
I saw the reset feature — which comes with a caution against using it. But there doesn’t seem to be any explanation as to how it works. The version number is a component of the tarball name. Is the tarball renamed? And the version number is embedded within the module source files inside the tarball . Are those changed? I presume not.
I’m sure all these questions will be answered once I stumble through this process the first time. But it would be nice to know in advance. The documentation is pretty thin on PAUSE mechanics.
Perhaps resetting the version will simply lower the current module down the list where it effectively becomes irrelevant. If I then republish it with a new, higher version number, PAUSE will see it as a newer version.
I still have a window of opportunity to cancel the deletions I submitted. Tomorrow, I’ll try cancelling the deletions try resetting the version number. I just hope that doesn’t take a week.
| [reply] |
|
|
> I saw the reset feature — which comes with a caution against using it.
The main caveat is that anyone who might have installed your dist with the unwanted version number won't automatically downgrade to a more recently uploaded version. All cpan clients will allow for manually downgrading versions but none that I know of do it based on upload date.
> But there doesn’t seem to be any explanation as to how it works. The version number is a component of the tarball name.
It doesn't necessarily need to be for the process to work. The PAUSE indexer parses the files in your upload to gather package-level version numbers. You could upload your dist as Some_Project.late_Aug.tar.gz or even da39a3ee5e6b4b0d3255bfef95601890afd80709.tar.gz; PAUSE is unconcerned with the name of the tarball as long as it is unique.
> Is the tarball renamed? And the version number is embedded within the module source files inside the tarball . Are those changed? I presume not.
No, nothing inside the tar is ever modified by PAUSE (anymore; there was an old bug where Windows generated tarballs with world writable files about 10 years ago and the system would go in and fix that and produce a second, renamed dist but I don't think it does that anymore). The version info stored in PAUSE is simply cleared from the backend. It'll be a blank spot in the database which allows you to downgrade version numbers whenever that package is indexed again (manually or on next upload).
Resetting the version is instantaneous.
| [reply]
[d/l]
[select] |
|
|
Just saw your update about re-indexing. Ok, the picture is becoming clearer. Thanks for the info and suggestions.
| [reply] |
Re: Help with PAUSE mechanics - replacing a bad module
by NERDVANA (Deacon) on Aug 31, 2022 at 17:02 UTC
|
While I also come from a background of preferring to do versioning differently than the perl standard, for CPAN I decided
When in Rome, do as the Romans do
The CPAN de-facto standard is that every version number is a float, and may or may not follow the v-string notation where minor number and release number occupy 3 decimal digits. Start with the major number at 0 until you have a more-or-less finalized API, and robust tests, then bump it to 1. Bump major when the API has a major change. Bump the minor for new features, and bump the release for misc bug fixes. If the long version number seems excessive, do what 50% of CPAN dists do and just roll the minor/release into a single 2-digit incrementing number like "0.45" and skip v-string entirely.
Regardless of numbering scheme, always write a change log that can be found and parsed by metacpan.org so that if someone cares about the release date, they can quickly jump into the change log and see what dates each version was released.
Only consider date-based versions if you have a module that is truly date-based, such as Mozilla::CA where the API has never changed and it is just a collection of official data files as-of a given date. Note that Mozilla::CA chose to write the entire date into the major version, rather than mess with minor/release numbers. | [reply] |
|
|
