How to Deprecate a CPAN Module

"This old house once filled with joy" by Don O'Brien is licensed under CC BY 2.0.

You may have noticed that the CPAN Security group recently got funded by Alpha-Omega to work on further securing the Perl and CPAN ecosystems. This means that A LOT OF CVEs are currently being issued. Since the group is not the arbiter of which modules are still in use (and this is largely an unknowable problem), there will be CVEs published for modules which probably can simply be deprecated.

Deprecating a module on CPAN is not as simple as pushing a button, so let’s run through what’s actually involved. The key thing to know here is that to deprecate a module you have to upload a deprecated version. This may seem counter-intuitive because uploading a new archive makes it look like the module is still under development, but none of this is going to change anytime soon. File it under “historical reasons” and get on with your day.

#First Consider Adoption

If you have decided that you no longer wish to maintain a module, you can mark it as available for adoption. This does not require a new upload and can be done directly from PAUSE. If you’re going this route, you can still upload a fixed version or you can wait for someone else to adopt and fix the code. If a module is still useful or has dependencies you may want to consider this option as more beneficial to the community. You are not required to hand off your module and, likewise, you are not required to deprecate it. It’s always your call to make. You can also choose to fix it or to do nothing at all.

#Choosing to Deprecate

#Flag the Module as Deprecated

Step one is flagging the module as deprecated. When I searched for resources on how to do this I, of course, found that Neil Bowers had helpfully already mapped it out, way back in 2015 in his Marking a distribution as deprecated blog post. That will walk you through the steps required to do the flagging. If you prefer to invoke an LLM, you can use TOKUHIROM’s handy deprecate-cpan-module skill. It also covers slightly more cases than Neil’s version (see Minilla).

A helpful practice when deprecating is to include a note about why the deprecation has taken place. See Crypt::SaltedHash for an example.

At this point I should note that the word is deprecated and not depreciated. The words are close and both are real words, so your spell check will not help you here.

#Upload Your New Version

At this point you may choose to ship a fix for the vulnerability along with the deprecation. You do not need to do this. Just keep in mind that the CVE will be displayed prominently on the module page if it remains unresolved so that other users are aware of the issue. Now it’s time to build your release and upload that to PAUSE either with your tooling or by using the PAUSE website directly.

#Maybe Delete All the Versions

At this point you may or may not be finished. After uploading your archive you can either delete the library from CPAN entirely or make yourself a sandwich and call it a day. You may be asking, why wouldn’t I just skip the deprecation and delete the module to begin with? The reason is that deleting a module from CPAN is more like archiving it. It continues to live on in BackPAN. This means that if you skip the deprecation and jump immediately to deleting your module, it will be hanging around in an undeprecated state in various places. Now, bizarrely, to quote myself:

BackPAN is an aggregation of what currently is and what at one point was on CPAN. For various reasons, modules can be deleted from CPAN before they have outlived their usefulness to the general public. […] There are various BackPANs and, unlike CPAN itself, there is no one canonical BackPAN. This leads to a confusing situation where not every BackPAN may have exactly the same files, so this bears keeping in mind.

If you use cpan.metacpan.org as the mirror which your CPAN client installs from, you are actually using a BackPAN, so in general you should be able to find what you need there.

You certainly do not need to delete your library from CPAN, but it’s a valid choice.

#Or Not

Maybe you’ve gotten a CVE and it doesn’t need deprecation at all – just a fix and a new lease on life. If that’s the case, kudos to you. Just remember that getting a CVE for your code is in no way a reflection on you as a person. If it were, I would feel terrible about myself. With the speed of security research increasing steadily we can expect many more CVEs to be published in the months to come. The increased volume, in the short term at least, will be part of the new normal.