A FIXIT-dive into an old CPAN module

Let’s have a thought experiment. Assume there is an Open Source-licensed Perl module published on CPAN that you care about, and that hasn’t had any updates in a very long time – what are your options?

In this blog post, I’ll take a dive into this problem, and use the Geo::Postcodes::NO module as an example. As of this writing, the module version is 0.31, and it’s most recent release was in September 2006.

Initial assumptions

Before we begin, let’s lay bare the most important assumptions I’m having. Your case may differ, but I think the following ones are pretty safe.

  1. There is a long-term need for this module, and we need it to be up-to-date and bug-free.
  2. We would like the module to be usable in an environment where recent or modern styles of developing Perl are preferred and used.
  3. We have the time, competence and calories to have the necessary conversations with the authors and their upstream peers.
  4. The author is available and approachable. If he or she isn’t responsive, then there are options for taking over as maintainer of the module after due diligence. This is a last resort though, so we won’t cover this here. If you need to do a lot, a good option is to ask to become a co-maintainer.
  5. Creating a new module from scratch is undesirable, either because it’s too expensive or because your business has decided not to spend time on writing basic software infrastructure.

What can or should be fixed?

Next is to take a quick look at the module in question! The Geo::Postcodes::NO distribution and it’s parent distro Geo::Postcodes (v0.32) are closely related, so we’ll consider them together.

What can or should be done with these is not a given. The best approach is always to reach out to the maintainer and tell about your situation.

With that said, I’ve found quite a few issues and list the most important ones (for me) below. There are more issues, but it’s O.K. to wait with those while we take a look at the first few.

Contribution hints

Contribution information for the module is missing (or at least, less than expected). The author ARNE has offered his email address, and after a quick search one can find his Github page. He hasn’t published this module there, though. If we are going to contribute with this, then just adding a CONTRIBUTING.md file is a probably a good place to start. If the module you are looking for has the same problem, then check out it’s “How to contribute” page on MetaCPAN (you can find a link to it in the menu there).

There’s another issue though – we can’t offer a pull-request! At best we can send a patch(1) file attached to an email. While this is a bit old-school and should still work (assuming the author accepts those), there might be better options available.

I’d check out GitPAN – a project that MSCHWERN started long ago & currently run by OALDERS. This project is a service where all modules released on CPAN are checked into a Git repository! GitPAN covers the entire history of CPAN, so after a quick look we find both Geo::Postcodes and Geo::Postcodes::NO there. With it, you can create a repository for you to work on, and possibly use to share with the author.

Out-of-date data

Since 2006, there have been multiple changes to post codes in Norway, and the update script that comes with the distribution isn’t usable any more. Not only is the URL endpoint it uses is long gone, but it seems that the published data format has changed too.

One option is to update the example update_no script, which shouldn’t be a big task. Another option is to outright replace it with something simpler – e.g. a Mojo::UserAgent based tool that for example produces a JSON file.

It may be best to talk with the author about what options are desirable.

Splitting code and data apart

As of 0.31, the update_no script actually rewrites the Geo::Postcodes::NO module itself! This is for many reasons a less-than ideal way of keeping data around. My favourite reason to reach for in situations like this, is the Zero-One-Infinity rule.

Allow none of foo, one of foo, or any number of foo. The only reasonable numbers are zero, one and infinity.

— Bruce J. MacLennan

In this case, the amount of postcodes should be considered as a case of “infinity”, so putting them into an appropriate storage format would probably be beneficial. In any case, the author should likely be involved here too.

Documentation updates

The documentation and many of the examples could benefit from a modernization. For example, installation is shown using the venerable CPAN.pm shell, which these days have been superseded by App::cpanminus and other, more friendly tools. Other examples talk about AJAX and CGI, which also have fallen out of favour.

API updates

If a different storage format is an option, then maybe it’s also worth to consider functional and/or promises-based API endpoints? This could become a major increase in scope, and there are still good arguments to not do this and instead focus on making the module smaller.

This module could just offer a good way of providing the latest data set, and then supply different tools for converting it into JSON or SQL INSERT statements, or whatever else people use to store this type of information. Again, it seems also here it’s best to have a chat with the author.

Involving the author

By now it should be abundantly clear that it’s necessary to have a chat with the author.

Lucky for me – Arne has been an active participant in the Oslo Perl Mongers community for many years! I’ve met him many times and know he is a friendly and quite approachable guy.

So I gave him a call, and told him about this article. This was his first comment:

Is anyone still using that old module?!

— Arne Sommer

That’s a good question – There is precious little feedback to get from CPAN on how popular a module is – especially if it isn’t considered a infrastructure (“toolchain”) module. MetaCPAN has a few signals to offer (e.g. the reverse dependency lists, or the rating system), but nothing useful when it comes to actual downloads.

While this module may not have many users both due to the scope of the module and it’s lack of updates, there may still be reason to keep it updated.

I’ve received almost no feedback on this module!

— Arne Sommer

I’m afraid this may be a common problem affecting many small-but-useful-module authors out there. My guess is that we “users” in general are not good enough at showing our appreciation for the work open source software authors do. I’ll even go as far as claiming this is a cultural problem that all of us need to work on. When was the last time you (who are reading this now) sent a friendly appreciation message to someone that wrote and published code for you?

Let’s not under-estimate how much a kind message can motivate.

It’s even possible to hire me to fix my code!

— Arne Sommer

This is actually a good point. One way to ensure your business dependencies are kept healthy and up-to-date with your needs is to hire the author! This isn’t easy and possible for everyone, though. Arne has this option available through is personal company, and I guess it doesn’t hurt to ask around if others offer this service too.

Tending relationships

I think there’s at least one clear thing to learn from this story.

Having a good relationship with your upstream software providers is a great idea and worth pursuing. Many go to Perl events, and while some might not be able (or willing) to attend events as often as you’d like, it doesn’t hurt to ask if they are going.

If your company would like to have a positive relationship with it’s upstream developers, you may even offer to sponsor an event they are speaking at, so they may have their flight & hotel expenses covered. There are lots of ways to go about this! The only thing that is guaranteed is that if you do nothing, then nothing happens.

If you choose to spend some time on having a relationship with your upstream (awesome!), but find it difficult – then don’t worry and keep doing it anyway. This community deserves people that are willing to play the long game, and playing the long game requires perseverance.

And finally; Should your efforts fail and you give up – remember, it’s still free to show your appreciation to your upstream devs by saying “Thanks!” now and then.

One thought on “A FIXIT-dive into an old CPAN module”

Comments are closed.