> 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:

• Re: Sane deprecation policy for a CPAN module? (Software Versioning and Exporter References)

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.

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.

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.

> 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.

Just saw your update about re-indexing. Ok, the picture is becoming clearer. Thanks for the info and suggestions.

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.