Re: Perl Module API update or new release

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

Comment on Re: Perl Module API update or new release Select or Download Code

Replies are listed 'Best First'.
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
Excellent Point! I was going with 0.1x as the new API, but since 0.10 will be v1/v2 (backward compatible), 0.2x should probably be the non-compatible version. UPDATE: Fixed version numbering from 0.1 to 0.1x and 0.2 to 0.2x.	[reply]