AskPerl: The Back-Compat Dilemma
Gentle reader, I need your advice.
Some years ago I created the Net::Appliance::Session Perl module. It allows the user to automate interactions with CLI-based networked devices (think routers, switches) - a sort of Expect but with some helpful domain knowledge. The module has turned out to be quite popular (which is important to my story), in use by many organisations.
There is a shopping-list of problems with the code, though, which makes both bug-fixing and feature development really hard. I've been planning a rewrite for over a year, and finally completed most of that in the past few days.
The new version is completely different internally, but that shouldn't matter much. The problem comes in that I've engineered a new "phrasebook" system for the scripted CLI interactions, and also the programmers' API has changed. [Edit: I should add that lots of long-asked-for features are included, so the rewrite did bring benefits for the user.]
Now, I guess that if I release this as Net::Appliance::Session with a major version bump it could cause havoc some time down the line when an innocent upgrades their server and in comes the new package and some maintenance script fails. Perl doesn't make it easy to deal with this (nor do most operating systems, either, of course).
However I'm loathe to change the module's namespace. I like its name, and it feels like chasing my tail if I just rename a module to indicate an incompatible API change.
Alternatively I could write a BackCompat role, but for starters that's a lot of work (the old API was huge) and I worry that things like error handling simply work too differently in the new version to massage. Also, should that role be enabled by default or via a flag at use-time?
I'm not a professional programmer, nor a key part of some large projects like Catalyst, Moose, DBIx::Class which I'm sure have had to deal with such issues in the past. I don't really know the best course of action, and I also don't have much communication at all with my user base (using this module is a sysadmin-practice "smell" so many don't own up to it).
I need your help: please have a think and let me know in comments what you might do in this situation. Many thanks!