Are all the changes only related to die vs. return error codes? A fatal error is pretty easy to make non-fatal with eval {}, so it sounds like it wouldn't be too difficult to make your code have exactly the same API as the old module, or would it? If it's easy, then perhaps you could even consider making whether errors are fatal or not a configuration option.

I wouldn't worry all too much about people relying on $@ values, unless specific $@ values have been documented in the module's docs.

BTW, I think it's ok if you name the module, that might help, it's all open source anyway :-)

The API changes I've made are deliberate, and ultimately for the good of the project. As an example of why I made these changes, there was a method that would:

1. return 0; if certain arguments are invalid, croak()s if others are invalid,
2. carp "Connection failed"; return 0; on connection failures. Yes, carp(), and
3. Not trap upstream exceptions itself, so it would die for any number of undocumented reasons the author did not anticipate (and no unit tests either!)

Since returning non-zero had no semantic meaning beyond "nothing broke," and the distinction between return 0; v. croak() was already ill-defined, I changed this sub to always croak() on error, thinking most implementations would already be eval{...}-ing that call, or risk premature death.

That's the biggest change. The other 3-4 examples are similar but simpler (fewer cases).

The documentation for the methods was generally good, except when it came to error handling. So I'm not really even going against the existing documentation, here, though I'm not using that as an excuse to break people's code. :-)

BTW, I think it's ok if you name the module, that might help, it's all open source anyway :-)

My personal choice. I'm not naming the module out of respect for the original author. I have not been able to reach them, and don't want them to hear about my feedback via this thread. I trust I've described the differences well enough for the general advice I'm asking for. (If not, please let me know!)

warn "Next version of Module::Unknown will die instead of returning un
+def.\n";
return undef;
[download]

That's a good way to add a deprecation warning for this sort of situation, and a simple solution. Thanks! And I have no deadline for this, so it's no skin off my asterisk to release such a version now, wait six months or more, then release another. My only hesitation is that it'd also be nice to give users a way to "opt in" to the changes ahead of time, and I was originally thinking of doing that in the code itself, but I reckoned that could get ugly, multiply the unit test requirements, and add two more likely points to introduce regressions. But you've got me thinking. Maybe append your warning with "For new code, use development version USERNAME/Module-Unknown-2.00_01.tar.gz" or something to that effect, with a blurb in the docs on how to fetch a dev build. Or is there an even cleverer way? :-)

Well, you can. It's more work but you could make this first new version behave like the old version, with aformentioned warnings, but also support the fixed API when they use it with use Module qw(:always-die); or use Module qw(:newapi); or whatever. Then your next version can switch to new api and silently ignore that flag.


holli

You can lead your users to water, but alas, you cannot drown them.

Well, one option is to release it as an entirely new module. The advantage of this is the people looking to upgrade can do so, and everyone else can putter along with their stable legacy code. You could put a reference in the original module's documentation about the new module and explain the improvements.

Otherwise, you probably just want to make sure it's as backward compatible as possible. If it's not that popular, it's less of a risk introducing changes.

Thanks for the suggestion. Unfortunately, it's already in the ideal CPAN namespace for what it does, and from a functional standpoint, my version adds a couple of features (strict superset, new features don't affect backwards compatibility), and fixes a few bugs. I broke backward compatibility intentionally, since it was pretty much impossible to use the module's existing API without some kind of undefined behavior.

Mostly summarising what other people have already said, but:

• Yes, do it. It sounds like an improvement.

• Document the changes clearly.

• Bump the major version number.

• Release a trial version (either an underscore in the version number or "-TRIAL" in the tarball name) at least a month before releasing it as stable.

• If there are other CPAN modules that depend on your module (especially if they're popular), do the authors a favour and download those modules and test them against your trial version. Submit bug reports and maybe patches if you've broken them.

Other monks have given good advice, but I just want to be sure that incrementing the major version number is not forgotten in the process. Arguably, that and a nice notice in "Changes" should be all you need.

The fact that the changes also make the API usable without relying on undefined behavior is also an argument in your favor. Generally, croaking on failure is appropriate if any reasonable application will need the func(...) or die ... pattern as is seen with Perl's own open most of the time. On the other hand, simply returning failure is better if an application might want to continue with some alternate method, as this sample from a test I recently wrote does:

my $fh;
open $fh, '<', \ $data
  or $fh = new IO::Uncompress::Gunzip (\ $data, Transparent => 1)
    or BAIL_OUT "cannot open string as file: $! $GunzipError";
[download]

That assumes that IO::Uncompress::Gunzip has its own XS magic for reading the contents of a scalar that is independent of the PerlIO infrastructure that the Perl core uses for that feature. So even if Perl was built without PerlIO, IO::Uncompress::Gunzip can still do it. (Other code in the module under test already relies on IO::Uncompress::Gunzip to decompress input data, so it was already in my PREREQ_PM list.)

Its simple

Release a development version (thats with a _ 01 in version number)

warn in the docs what the change is gonna be, fix what needs fixing

Wait for complaints (ex 1week or 1month)

Then in a week or month release the next stable version and you're done

Then wait the next ten years for complaints from regular fools who dont read docs or have test suits .... ;) It really is that simple ;)

For one example you can see about CGI changes since 4.03 2014-07-02

4.05 (LEEJO on 2014-10-08)
4.04_05 DEV (LEEJO on 2014-10-06)
4.04_04 DEV (LEEJO on 2014-10-06)
4.04_03 DEV (LEEJO on 2014-09-29)
4.04_02 DEV (LEEJO on 2014-09-28)
4.04_01 DEV (LEEJO on 2014-09-20)
4.04 (LEEJO on 2014-09-04)
[download]

LEEJO gets commit bit and sets about gutting ye olde tool bucketbagbox ...