http://qs321.pair.com?node_id=11101832


in reply to Deprecating a CPAN Module

Hello mikkol,

put very near to the beginning in the module docs, in the synopsys maybe, like XML::Simple

SYNOPSIS

PLEASE DO NOT USE THIS MODULE IN NEW CODE.

[download]
Add some explication (security? speed? uses of deprecated features?) possibly followed by a list of alternatives. I think you can delete from CPAN but seems a bit too much.

For me as user will be enough.

Thanks for looking with criticism to your own modules anyway

L*

There are no rules, there are no thumbs..
Reinvent the wheel, then learn The Wheel; may be one day you reinvent one of THE WHEELS.

Replies are listed 'Best First'.
Re^2: Deprecating a CPAN Module
by stevieb (Canon) on Jun 24, 2019 at 21:59 UTC

    ++ overall, but:

    "I think you can delete from CPAN but seems a bit too much."

    Please don't delete distributions from the CPAN, *especially* when in a deprecation cycle.

    There are very valid reasons why someone might need to come back and fetch your last version released. For example, someone could have an enormous corporate installation of software that requires it. If that one distribution disappears, the whole thing will fall apart.

    Loud warnings within the distribution as per what you and haj already stated, the deprecation flag, and honestly, if it's a major security thing, I might go as far as putting a warn "SECURITY ISSUE: This dist is deprecated; See docs for details\n"; within an instantiation method, or frequently used function.

    Thankfully, I've never had to go this far as I've never been made aware of security issues in my software (yet!), but I certainly have deprecated distributions before. They sit on the CPAN collecting dust, with the relevant notices in the POD.

    See the DESCRIPTION in RPi::WiringPi::Constant for example.

    If I ever were to have a distribution that I had to absolutely ensure didn't get installed after deprecation period (typically I've heard and would adhere to a two-year cycle), I might add a croak() to the code, with the warning pointing to a URL or something. This ensures previous code still works, but new installs would fail. Generally, this would happen if my dist is being used by someone elses software, and I'd be notified eventually.

    Worst case scenario, if you need to go extreme like croak()ing because of security or other issues, I'd do a reverse dependency lookup, see who's using my bad dist, and attempt to contact them directly before taking significant action.

[reply]
[d/l]
[select]
      Please don't delete distributions from the CPAN … There are very valid reasons why someone might need to come back and fetch your last version released

      Wouldn't BackPAN be sufficient for this purpose?

      (Any time I upload to pause.cpan.org, a message is displayed encouraging me to clean up outdated distributions to help reduce the storage burden for CPAN and its mirrors. It assures me that users can always find old versions on BackPAN, as it intends to be a permanent archive that only under exceptional circumstances might a distribution be deleted from it.)

[reply]

        If it's on BackPAN, it won't be installed. You have to manually fetch it from there, and typically, most users wouldn't be familiar with the process when their 50-distribution project installation fails because something can't be found on the CPAN.

        Cleaning up your PAUSE versions just means removing the ones that aren't relatively current. If you remove the dist entirely from the CPAN (all versions essentially), it won't be found using typical CPAN tools period.

        ie. Standard CPAN tools don't go looking through BackPAN for previous versions. Those are considered legacy (at least this is my understanding).

[reply]

In Section Seekers of Perl Wisdom