Maybe you could provide the full http://www.perlmonks.org/index.pl?node_id=310337 URL in your POD. :)

I don't like the idea of your debug() — far too hackish a way to enable deprecation warnings. Probably the best option is to use warnings::register instead. Another idea would be a companion module which merely sets a package variable; it could be then both be used from all the usual places as well as autoenabled by adding -Mdeprecated::warn or some such to PERL5OPT.

I wasn't sure if Craft was active anymore, but the whole Monastery is getting pretty catacombish about where to put stuff. I sort of wish it was all just "discussion" or "code." But that's a separate conversation.

There are a thousand ways to flip the big debug() switch, and this is "sorta" the test that I settled on for the library I manage. I wanted the warnings to be invisible for uninitiated end-users, and to be visible to developers who didn't even know that deprecated.pm existed. It's a compromise, but it's all in a separate function. It'd be neat if 5.8.2 adopted it (or even just the concept) and they could do whatever they wanted with debug(), but I just wanted to get the thing done.