Oliver Gorwits

Hi Oliver

I fear there is no easy solution to this dilemma. I’d predict some will say bump the version #, and some will say call it Net::Appliance::Manager (or somesuch), and some will not comment.

I.e. The decision is yours. If you like the name keep it. A major version bump is a commonly-accepted warning that the API has or may have changed, and if that’s the best you can do, do that.

Cheers

You can also force a prompt upon users installing the new version to view the upgrade warning and explicitly accept it. I have seen that done by some modules in the past. Also, you might get more detailed advice if you give a few examples of how the API has changed. I looked at the new branches on your github repository, but didn’t see any Pod.

I think the first thing you have to do is to understand on the behavior of your users.

Some users update regularly, some update once in a while, some check the changes log, while others check a website, a mailing list or are in contact with the author.

Secondly, you need to decide how versioning happens in your code. Are you using the basic x.yy where “x” is a major version and “y” are iterations of it? are you using x.y.z where “x” is a massive change, “y” is a stable release series and “z” are iterations? In Dancer, we use x.yzzz, “x” being the hugely major version which will only change in a very late future, “y” being the release series and “z” being iterations.

Then you decide on your deprecation policy. Dancer now has x.(even number) as a stable release and x.(odd number) as a development release. Same as Perl. How often do you deprecate?

Our deprecation policy is: deprecate, as a warning, in development, which then ripens to stable. Then, the next development version removes it and then it doesn’t appear in the stable release again. You can remove every two versions, if you like.

You can also think of how you’re alerting your users of the change (which is why it’s important to know your users). If you have a mailing list, you post about the issue, you can put it in the changes file, if you think they read it. If there’s a website, write it there. If it’s on CPAN, you can mention it in the POD. You can put it on installations. You can add a warning to start up, which DBIx::Class were very successful with. As soon as someone “uses” the old syntax (in the deprecating version(s)), you can warn them (which hopefully they see in output or logs) about a deprecation of a feature(s).

Hope it helps, and good luck! :)

I read the current documentation on CPAN, and it sounds like the old version supports user-provided phrasebooks. Does the new code support old phrasebooks? It probably needs to, and if it did then the old default phrasebook could be included as an option. You could even leave it as default, and require a method call to switch to the new one.

Here’s an option that my old boss used to call GFD (Gross, Foul, and Disgusting): For the next release, add an import option for :newapi and override the import method. The import method looks for the option and then does a bunch of namespace insertions.

If the newapi option is not requuested, you’ll copy subroutine references from Net::Appliance::Session::OldAPI into Net::Appliance::Session. The OldAPI module would just be a copy of the current Session module. You can copy references like this:

*Net::Appliance::Session::connect = *Net::Appliance::Session::OldAPI::connect;

You can also loop over the keys in %Net::Appliance::Session::OldAPI, which will be shorter and get you any package globals you might be using too. (You’ll probably need to test each value with ref to see what it is before you copy it.)

If the newapi option is requested, you’ll do the same thing but copy the new code from Net::Appliance::Session::NewAPI instead.

You’ll need to create OldAPI and NewAPI for your other modules too, and copy them the same way.

What this will do is make your top-level namespace behave like the old code or the new code based on a single option provided when the caller uses N::A::S, with the default being old behavior. You can also add a warn statement to N::A::S::OldAPI::connect that tells the user that the old api is deprecated. Then next year you can remove this hack and just put the new code where it belongs.

One advantage of renaming is that its easy to have both the old and new version installed simultaneously. That makes migration much easier.

One advantage of renaming is that its easy to have both the old and new version installed simultaneously. That makes migration much easier.

There are problems either way, but I personally find it more confusing to move to a different name than to recognize huge bump in version numbers.

If you are thinking of going from 0.7.9 to 0.8.4 that will still be confusing. Go big or go home? Say 0.7.9 to 2.0.0 Since you have added requested changes I would expect the name to stay the same.

I’ve come to expect big changes when I see that kind of jump and expect compat issues too. When there is a name change I instantly think ‘oh shit! will this even work the same?’ or ‘noooo, they stopped supporting it’ where they is obviously you in this case.

If you added huge feature differences like ‘now works with Commodore64 and VAX/PDP-11 (pre ‘82 releases only)’ or ‘added support for Zune(beta) and MS Excel 2012’ then a name change is appropriate. Anything that essentially makes it a different application requires a name change.