You say that the "behaviour" isn't optimal, but you don't clarify whether the actual interface is a problem or not.

Is "behaviour" what's happening behind the scenes that if you change it, it'll affect the interface the user uses or the results/returns/output? If not, make the changes, make sure all existing tests pass, write new tests, and you're good to go.

Otherwise, if the user experience will change, as LanX said, you have a few options:

I'd stay away from the last option though, as personally I see it only as a stop-gap for a transition into something new. It'll add complexity to the already inefficient behaviour you've already got.

As far as time frame, I'd give at least one year for providing critical updates (security, data corruption etc), then at that time, change the notice from deprecated to unmaintained.

I was meaning the interface/UX only. I.e. changes that may break the results and/or side effects of documented usage.

Either by expanding the API in the same module, or by writing a new one.

Sorry. Maybe not what you wanted to hear. :)

This is definitely the best option.

However, we'd run out of CPAN namespaces though if authors start renaming modules upon realizing they made a poor design decision in the past.

Which begs the question: how to minimize the damage from a possible bad decision in the first place? I think there should be some rules of thumb.

> we'd run out of CPAN namespaces

Depends on how creative you are when naming the new module. See for example XML::XSH versus XML::XSH2.

($q=q:Sq=~/;[c](.)(.)/;chr(-||-|5+lengthSq)`"S|oS2"`map{chr |+ord
}map{substrSq`S_+|`|}3E|-|`7**2-3:)=~y+S|`+$1,++print+eval$q,q,a,
[download]

> I think there should be some rules of thumb.

In open source we should rather talk about habits and culture, if there are rules they developed from tradition.

> how to minimize the damage from a possible bad decision in the first place? 

Flag your module as experimental, till its implementation is fixed.

Or contact the users, if there are no reverse dependencies you should be fine.

> we'd run out of CPAN namespaces

Not if you keep the old API for a deprecation period.

For instance you could refactor the "bad" part of module XXX to XXX::Old, and use it internally.

Or new users need a use XXX :modern attribute or version number during a grace period.

You should know best what is feasable!

Sorry, I'm not aware of any policy which will safe you from being called names by old users if you break their code, even after warning them for years.

It's up to you. .. :)

Just have a look at CGI.pm

Cheers Rolf
_{(addicted to the Perl Programming Language :)
Wikisyntax for the Monastery FootballPerl is like chess, only without the dice}

G'day Dallaylaen,

[Note: It is unclear from your post whether the deprecation warnings are from your own or third-party CPAN module(s). If the former, some of what follows may not be pertinent.]

You wrote about "... backward compatibility ..."; however, you also need to consider forward compatibility.

If you search perldiag, you'll find entries containing text like:

"... is deprecated, and will disappear in Perl 5.xx ... (D deprecated) ..."

"Deprecated ... This will be a fatal error in Perl 5.xx ... (D deprecated) ..."

"... (F) ... was deprecated in Perl 5.xx, and became fatal in Perl 5.yy."

When you use modules, you can specify a minimum version for those modules. You can also specify a minimum Perl version with use. Also see the no function.

The if pragma can be used to conditionally load modules based on the current Perl version. (Its conditions are not limited to this type of check.)

In your Makefile.PL, you can specify a minimum version for both Perl and dependent modules: see ExtUtils::MakeMaker. Module::Build offers similar facilities.

Provide clear documentation. Obviously, this will depend on how you end up handling this. You might provide a final end-of-life version of X::Y::Old with doco recommending changing to X::Y::New. You might update the current module with doco explaining why this version is preferred. Use POD and the README, INSTALL and Changes files as appropriate. I'd recommend using cross-references (e.g. "See the INSTALL file for details.") rather than copy/pasting tracts of doco from one place to another (which will almost invariably end up getting out of sync).

Thanks for asking this -- it reminded me I need to update Writing Solid CPAN Modules with advice on CPAN Module Versioning.

Short Summary

For a new module, start by adding the line:

our $VERSION = '0.01';
[download]

use vars qw($VERSION);
$VERSION = '0.01';
[download]

When you have finally produced a stable, production quality API, on which users have come to depend, it is a good idea to indicate that by bumping the module version to '1.00' or higher. And further to set your CPAN distribution's CPAN::Meta::Spec's release_status to "stable" (other values for this piece of CPAN distribution metadata are "testing" and "unstable").

General Software Versioning Refs

• Software versioning (wikipedia)
• SemVer (Semantic Versioning in Software Management)
• This node mentions "C++ as a Live at Head Language" talk by Titus Winters, which describes Google's real world experiences with library versioning in huge code bases and why SemVer proved inadequate for them.
• API Change Strategy
• Stack Exchange question

CPAN Versioning Refs

• perlmodinstall - Installing CPAN Modules
• CPAN::Meta::Spec by xdg - specification for CPAN distribution metadata, see especially release_status field (with values 'stable', 'testing', 'unstable').
• perlmodlib : see "Guidelines for Module Creation" section. From that section: "To be fully compatible with the Exporter and MakeMaker modules you should store your module's version number in a non-my package variable called $VERSION. This should be a positive floating point number with at least two digits after the decimal (i.e., hundredths, e.g, $VERSION = "0.01"). Don't use a "1.3.2" style version. See (Module Version Checking) in Exporter for details". From the "Version numbering" sub-section: "The most common CPAN version numbering scheme looks like this: 1.00, 1.10, 1.11, 1.20, 1.30, 1.31, 1.32".

Note: apparently Perl Best Practices got this wrong (in Modules chapter, 221. Use three-part version numbers; 222. Enforce your version requirements programmatically) and so is a dubious reference on CPAN module versioning.

See also:

• Version numbers should be boring by David Golden
• VERSION confusion by chromatic at modern perl books
• A guide to versions in Perl by Grinzz
• version - CPAN version module by Leon Timmermans
• only - CPAN only module by Ingy
• Licensing META files on CPAN (perlmaven)

META.yml and META.json

• ExtUtils::MakeMaker
• Module::Build
• Module::Install
• Dist::Zilla (See also: Dist::Zilla::Tutorial, dist-zilla on github, and dzil.org)

Some Perl Monks Versioning Nodes

• Module version numbers best practice by hippo
• Re^2: Module version numbers best practice (meaning--) by tye (using dates as version numbers runs into the problems of trying to assign meanings to version numbers)
• Re: Module version numbers best practice by admiral_grinder (sync the version numbers of your CPAN package with the version that your entry module uses)
• Seeking thoughts on version numbers in modules by xdg (2004)
• Can't use three part version number for CPAN modules by arc_of_descent (2006) - advised to stay away from PBP version numbers
• What basic things should I know about versioning modules? by nysus (2017) - Note that our $VERSION = "1.23"; seems to be the most compatible with the various Perl tools that parse code to find information on modules (taken from this reply by haukex)
• $VERSION in module files by bliako (2020) - see Re: $VERSION in module files by haukex
• Re^11: Perl Contempt in My Workplace (2021) asks for meaning of version 1.0 and how to indicate whether a module is experimental vs supported and in production.

• How should I install different versions of a module?

Deprecating a CPAN module

• XML::XSH by choroba - There is a big warning right at the top "This module is deprecated, use XML::XSH2 instead".
• XML::XSH2 by choroba - This is the current one. Looking forward to XSH3, XSH4, XSH5, ... :)
• Hmmm, CPAN::Meta::Spec does not appear to have a Deprecated status, release_status has only "stable", "testing", "unstable".

Perl Monks Nodes Added Later

• Help with PAUSE mechanics - replacing a bad module by PUCKERING (Aug 2022)
• Modulino to report ip address changes by davies (Oct 2022)
• Unable to release modulino to CPAN by davies (Oct 2022)
• Choosing the right module by Bod (Oct 2022)

• Version Control - GitHub and CPAN by Bod (2023)
• Re: Deciding dependency versions by Tux (2023)

Note: Many updates were made long after the original reply - in preparation for later insertion into Writing Solid CPAN Modules

Well at least I got my version numbers right, apart from skipping x.y0 which I'm going to take up now.