Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked
 
PerlMonks  

Sane deprecation policy for a CPAN module?

by Dallaylaen (Chaplain)
on Nov 17, 2018 at 10:45 UTC ( #1225945=perlquestion: print w/replies, xml ) Need Help??

Dallaylaen has asked for the wisdom of the Perl Monks concerning the following question:

Hello esteemed monks,

Say I have a CPAN module and I found out that its behavior is not exactly optimal. So I would like to change it, but there may be users out there! How do I change my module before backward compatibility locks me into my bad decisions? And what modules should I look into that do the right thing (tm)?

My current policy is to keep old behavior with a deprecated warning for 5 releases (not including the bugfix), but I guess that's not the best I can do.

Thank you.

  • Comment on Sane deprecation policy for a CPAN module?

Replies are listed 'Best First'.
Re: Sane deprecation policy for a CPAN module?
by stevieb (Canon) on Nov 17, 2018 at 14:43 UTC

    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:

  • Write a brand new distribution, deprecate the old. In the old one, point loudly to the new one for new users
  • Add new functions/methods alongside the existing ones that are already in use. Deprecate the latter ones, leave them for back-compat, but promote the new subs for new users, and existing users who may one day update their own software
  • Add new flag(s) to the existing subs, so that the different "behaviour" is called behind the scenes if the user sets this flag.
  • 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.

Re: Sane deprecation policy for a CPAN module?
by LanX (Cardinal) on Nov 17, 2018 at 11:51 UTC
    My preference is to keep the old code for backwards compatibility and flag it as unsupported.

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

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

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

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

Re: Sane deprecation policy for a CPAN module?
by kcott (Bishop) on Nov 17, 2018 at 20:26 UTC

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

    — Ken

Re: Sane deprecation policy for a CPAN module? (Software Versioning)
by eyepopslikeamosquito (Bishop) on Nov 18, 2018 at 20:43 UTC
      Well at least I got my version numbers right, apart from skipping x.y0 which I'm going to take up now.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://1225945]
Approved by choroba
Front-paged by Corion
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (5)
As of 2021-05-18 11:21 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Perl 7 will be out ...





    Results (178 votes). Check out past polls.

    Notices?