by · ·5 min read ·1,002 words
"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.
#Addendum: A Note from brian d foy
After I posted this, brian d foy added some helpful context on Reddit:
I recommend that you leave even the latest version of your dead and broken module on CPAN. When I’ve completely removed them, meaning that PAUSE does not index them and you can’t install them normally with cpan, I soon receive complaints that the module is missing. Some of that is from the appropriately zealous third party packagers, and some is from the two people in the world who have built enterprise software around it. All of this despite the absolute garbage quality of whatever I created, never finished, and never personally deployed to any good purpose. It’s just less work to leave the module there.
And, if you do want to get rid of a module because you don’t want it any more, you can add the repo to my CPAN Adoptable Modules so the repo still exists somewhere, just not where you have to see it.