in reply to Controlled CPAN distribution breakage

Is there any way to keep the old API at the same time as adding the new API? You could then add a deprecation warning to the old API methods, so that users of your current API would be aware of the pending changes. At this time, you could increment the MINOR version number (the Y in X.Y), indicating a backward compatible API change. You may want to push the deprecation warning off to the MAJOR version change. This decision depends on if you consider emitting warnings as breaking your API -- I can see arguments either way.

Once that has been available for a sufficient amount of time, then break your old API, perhaps even dying on the old API calls, and increase the MAJOR version number, indicating a backward-incompatible API change.

--MidLifeXis

Replies are listed 'Best First'.
Re^2: Controlled CPAN breakage
by dwalin (Monk) on Feb 07, 2014 at 02:59 UTC

    In fact the API stays mostly compatible, with several changes that should not, in theory, be breaking but I have neither time nor desire to do the proper regression testing so I assume that some breakage will ensue.

    I'm more concerned about CPAN tools not making any distinction between major versions. It would be so much more convenient if the auto tools like cpanp and cpanm would take module versions into consideration and didn't jump from 1.x to 2.0 for example, instead following the current 1.x branch until the user makes a conscientious decision to upgrade. Unfortunately that seems not to be the case, and when I release the next major version all the tools will happily adopt it as the newest-and-greatest, thus causing potentially unwanted breakage and grief for the unsuspecting users.

    One option is to change the name of the distribution, thus avoiding the problem altogether. That seems silly because in fact it's the same thing; I just want the users to review and retest their code, adjust it to the new version and deploy it as they seem fit instead of forcing them to upgrade at what is usually a very inconvenient time.


    Regards,
    Alex.

[reply]

      It would be so much more convenient if the auto tools like cpanp and cpanm would take module versions into consideration and didn't jump from 1.x to 2.0 for example, instead following the current 1.x branch until the user makes a conscientious decision to upgrade.

      Well, hah :)

      See https://metacpan.org/pod/CPAN::Meta::Spec#prereqs for the bare-bone-ness

      See Task for advanced bones

      All you need, to get cpan/cpanm not to jump from 1.x to 2.x is add checks in all the related Makefile.PL equivalents, that does  die "ABORTING; WILL NOT FORCE UPGRADE TO 2X VERSION WITHOUT Task::Foo2X\n" if not require Task::Foo2x;

      Then Task::Foo2x does explicitly install  DWALIN/Foo-2.0.1.tar.gz and all the stuff

      Then you get everything you want, but naturally you have to update the 1.x version to have this enhanced Makefile.PL equivalents

[reply]
[d/l]
[select]

        Not sure I understand what you're saying here. What exactly Task has to do with this problem? I'm not trying to bundle the whole suite of modules in one distribution, I'm trying to find an easy way to prevent the modules dependent on Foo from upgrading it. Say, I publish Foo::Bar that depends on Foo 2.0; that will make cpanm install Foo 2.0 automagically whenever Foo::Bar itself is updated - just because cpanm will fetch the greatest version of Foo::Bar available without regard to the major versions.

        If you're suggesting to use Task::Foo2x as a marker of sorts, then it can be done with an empty module instead. I think.

        Also I'm not sure that the approach you're advocating will bode well with the CPAN testers. I really appreciate the reports and don't want to lose them; dying in Makefile.PL would most probably break the toolchain and require manual intervention. Which I really doubt anybody would do.


        Regards,
        Alex.

[reply]

In Section Seekers of Perl Wisdom