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.)

In reply to Re: Minor API changes in 10-year-old module by jcb
in thread Minor API changes in 10-year-old module by wanna_code_perl

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.