Perl Module API update or new release

VinsWorldcom has asked for the wisdom of the Perl Monks concerning the following question:

Monks,

I maintain a CPAN module Cisco::Management which I wrote / released when I was just learning how to write modules. Needless to say, there is much room for improvement and I've decided to break the monolithic code into sub-modules under the main Cisco::Management grouping.

This requires that I change the current API slightly:

Instead of "use Cisco::Management", it'll be "use Cisco::Management::MODULE"

So I thought I'd take the opportunity to standardize and change existing accessor calls as well as add all the missing ones.

I made note of this in the latest release (0.08) saying it was the last in this line / format. Not sure who actually reads the README / POD.

QUESTIONS

Should my next release be under the same namespace (Cisco::Management) with initial backward compatibility (warnings) for the new API?
Should I release the new version under a new namespace (Cisco::Management2, Cisco::SNMP, etc)?
Any recommendations / previous experience to share?

I don't want to clutter the namespace, abandon a module and start a new one if there is no need. I don't know how many people use this (I'm guessing very few) so impact may be minimal as long as backward compatibility is maintained for the first new API version release.

Comment on Perl Module API update or new release

Replies are listed 'Best First'.
Re: Perl Module API update or new release by MidLifeXis (Monsignor) on Mar 24, 2015 at 13:43 UTC
How about something along the lines of `use Cisco::Management api => 2;`, and have that top-level module load either the v1 compatible module (the current code) or the v2 compatible module (the new stuff). This would allow you to, at some future point in time, deprecate the v1 module, put warnings to the user a few releases prior to decommissioning the v1 API, etc. From the perspective of a timeline: load the v2 API if `api=>2` import parameters are provided, v1 as the default. ~~emit a warning if an api import parameter is not provided~~ Emit a warning if a v1 api is selected (even as the default) Change the default to v2. If you use the X part of X.Y[.Z] versioning to indicate API breakage, this is where you would update that part. warn that support for v1 is deprecated drop v1 support Update: requiring the api parameter changes the top-level `use` semantics for the module, and may not be what you want to do. Update 2: Add comment about updating the X part of the module version string. --MidLifeXis	[reply] [d/l] [select]
Re^2: Perl Module API update or new release by VinsWorldcom (Prior) on Mar 24, 2015 at 14:35 UTC
Thanks, that was more or less my original thought. Just not in that much detail since I'm not a software developer / maintainer by trade - don't know the nuances of deprecating support, etc. I plan to leave version 0.08 on CPAN (released Jul 2014) which is the last "API v1" and its README and POD talk about it being the end. You can stay here if you fear change. Just no more support / updates. My next upload to CPAN would be version 0.10 which maintains backward compatibility but produces warnings. The README and POD describe using 0.08 if you fear change. This version allows you to keep running (with warnings) while you migrate code to the new API - which works in this version. This would be release now (8+ months after 0.08 README and POD talked about the new things coming). Then 0.11 would be the "API v2" only - no backward compatibility. I could release this now also (although automated CPAN updates grabbing the latest version would be an issues since this won't be backward compatible. Perhaps December 2015 / January 2016 release? I usually remove old versions from CPAN (knowing they can be found on BackPAN) to be a good PAUSE citizen, but I'd leave 0.08 and 0.10 (APIv1 and APIv1/v2 compat.) along with the 0.11+ current version that provides new features / updates / fixes for a year or so.	[reply]
Re^3: Perl Module API update or new release by RonW (Parson) on Mar 24, 2015 at 17:07 UTC
Then 0.11 would be the "API v2" only - no backward compatibility. I would suggest that the "APIv v2 only" be version 1.0 (or even 2.0) to emphasize the significance of the change.	[reply]
Re^4: Perl Module API update or new release by VinsWorldcom (Prior) on Mar 24, 2015 at 18:04 UTC
Re: Perl Module API update or new release by Anonymous Monk on Mar 24, 2015 at 03:39 UTC
I would use a new namespace for the new version, that way you could rewrite it freely without having to worry about backwards compatibility or breaking anyone else's code. In the original version, you could reference the new version at the top of the documentation and recommend that it be used for new projects.	[reply]