I have a module on the CPAN and I have to change its API (standardization issues).

Here's how I'm thinking to do it:

And then, perhaps after six months or a year, I would release a new version without the old API.

I'd like to know what others think; has anyone had this kind of experience before?

Replies are listed 'Best First'.
Re: Changing API's of CPAN modules
by PodMaster (Abbot) on Mar 12, 2005 at 14:20 UTC
    Depends on how popular your module is :)

    Instead of changing the API, I think it's much better/easier to rename your API and start fresh, so you don't have to worry about deprecation warnings or early adopters whining about the changes.

    All you do is release a final version (unless you want to maintain both APIs) of the old API with a note in the documentation saying something like You should use API2 as API is no longer being maintained (if you wish to take over maintenance ...)

    MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
    I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
    ** The third rule of perl club is a statement of fact: pod is sexy.

[reply]
Re: Changing API's of CPAN modules
by brian_d_foy (Abbot) on Mar 12, 2005 at 21:55 UTC

    Don't forget to bump the major version of the module (i.e. from 1.x to 2.x). Leave both the old and new versions on CPAN. Don't forget that some people will use other people's scripts that want the old module: the script still works so they don't have any reason to upgrade.

    The deprecation warning is nice, but I'd at least have a way to turn it off.

    Give plenty of notice of what's going to change, and give users a chance to comment on it informally. Hoepfully you know about some of the people who depend on your module and don't want to pull the rug out from under them.

    Good luck :)

    --
    brian d foy <bdfoy@cpan.org>
[reply]
Re: Changing API's of CPAN modules
by belg4mit (Prior) on Mar 12, 2005 at 15:55 UTC
    Kill the "deprecated warning" idea... that would be lovely to have one's Apache logs filled with clucking from a module. This is what major versions are for. Change from say 1.x to 2.x and it's perfectly acceptable to break things as long as you document the fact that things will be broken.

    --
    I'm not belgian but I play one on TV. On dit que je parle comme un belge aussi.

[reply]
Re: Changing API's of CPAN modules
by pprindeville (Novice) on Aug 14, 2014 at 00:44 UTC
    Revisiting this issue: what if you want to have the same source module provide 2 versions of the same of the same API?

    And how do you handle the case of methods themselves having changing API's?

    For instance, for a particular module v1.5.1 might have a ::new method that takes one set of parameters and generates an object with a particular internal representation, but v2.0 might have a different set of inputs to the ::new method and an incompatible internal representation of the class object.

[reply]
[d/l]
[select]

      Instead of having one module provide both APIs, you could provide a new module for the new API and either use the old module under the hood, or refactor the common code out of the old module and both variants of the module use the worker module under the hood.

      If your module is OO (::new implies it is) provide a different constructor for each API variant. Your module code can then use any applicable common code and people get to choose to use the new API if they want.

      Perl is the programming world's equivalent of English
[reply]
      sub new1 and sub new2? Cog - the original and Cog2 - the improved?
[reply]

Back to Meditations