in reply to Sane deprecation policy for a CPAN module?

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

  • Comment on Re: Sane deprecation policy for a CPAN module?

Replies are listed 'Best First'.
Re^2: Sane deprecation policy for a CPAN module?
by Dallaylaen (Chaplain) on Nov 19, 2018 at 04:16 UTC

    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.

[reply]
      > 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]
[reply]
[d/l]
        Dancer2 also comes to mind. Oh and Test2. I wonder if anyone got to *3, apart from IPC::Open3 (for which it is not a version).
[reply]
      > 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

[reply]
[d/l]
        Just have a look at CGI.pm

        "Yes, but ..."

        The v4.x series of CGI.pm has introduced some drastic changes, but they were poorly communicated (see Re: Replacing CGI.pm, Re^2: "CGI::param called in list context" confusion, "CGI::param called in list context" confusion, and probably many more threads). Take it as a bad example.

        If you introduce new warnings or errors, document that fact. If you break existing code, document that fact. Don't hide such information five levels deep in the filesystem. Put it into the main documentation, and make sure it is read. "Incompatible Changes" is a great heading for such kind of information. Also list such changes in your change log.

        Depending on how complex your module is, and how much documentation already exist, you may want to move parts of the documentation into another POD file. If you introduce a new API, you could move the documentation for the old API to Whatever-API-v1.pod and link to that file from the main documentation. If you build up a huge amount of incompatible changes, do the same and place the link to the Whatever-incompat.pod in a prominent place of the main documentation.

        If your module is a frontend to several backends, like DBI, keep the backend API documentation out of the main documentation (compare with DBI::DBD). Document what is needed for someone using the frontend.

        A second problem of CGI.pm's documentation is its structure. It reads more like a cookbook and less like other module's documentation. Don't get me wrong, I like to have a cookbook, especially for complex modules. But it should not be the main documentation. After a while, you know the most frequently used functions by heart, and you want to look up other functions by name, not by purpose. Compare with DBI.

        The cookbook part of CGI (the "HTTP COOKIES" and "SERVER PUSH" chapters and all chapters with headings matching /ing/i, perhaps except for "Calling CGI.pm routines") should really be in something like CGI::Cookbook. In the main documentation, I expect to find documentation for all public methods. I also expect to find the method names in the table of contents, i.e. in headings. Again, see DBI.

        With all the cookbook parts removed, the main CGI v4.x documentation is quite thin:

        • A big fat notice explaining that CGI.pm is no longer in core. That's for changes.
        • Half-hearted deprecation of HTML-generating functions. That's important, because it changes the API.
        • Compatibility with the ancient cgi-lib.pl. That was touched last time two decades ago, but people still seem to use that API.
        • The usual stuff: name, synopsis, description, license, credits, bugs, "see also". All very short. (And it should not be longer.)

        What's missing?

        • A link to a changes document
        • An overview of incompatible changes, like warnings when using param() in list context, or the ever-changing handling of file uploads. You have to search that information in the cookbook part.
        • Method documentation, by method name. All the information that is burried in the cookbook.

        Alexander

        --
        Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)
[reply]
[d/l]

In Section Seekers of Perl Wisdom