Zen and the Art of Package Maintenance

At this year’s Wagtail Space US, a conference dedicated to the Wagtail content management system, my friend Tim Allen hosted a panel on (Wagtail) packages, the challenges of maintaining them, and the small joys of being a maintainer. It was a good discussion, and you should watch the full panel if you’re interested (once it’s posted). I have some reflections on I wanted to write up coming out of it.

A photo of four people, the nearest one speaking
Left to right: Tim Allen, Vince Salvino, Jacob Topp-Mugglestone, Will Barton.
Photo by Tom Dyson

I shared the panel with Vince Salvino of CodeRed, Jacob Topp-Mugglestone of Torchbox, in addition to Tim from The Wharton School (and an enduring fixture in the Django and Wagtail communities). Tim or Vince made the observation that with the four of us the maintainers of the most-used Wagtail packages are all in one place. This speaks to larger growing pains the Wagtail community is having. Each of us have organizations that provide active support for us contributing to Wagtail, maintaining packages, etc. Not everyone is so lucky.

A theme of Wagtail Space 2024 was getting more people involved in the Wagtail community, as users, contributors, and maintainers. Tom Dyson, opening the conference, asked how do we continue to grow? How do we build the community? I think package maintainers have an outsized role in this.

For those of us who maintain packages I think there are two overall situations in which other people will interact with our software:

  1. When they’re trying it for the first time
  2. When they’re updating it (whether for its own sake or because they have to for a Wagtail update)

I believe most people find our packages by searching for a solution to a particular problem they’re trying to solving. They encounter our package and it either solves their problem or comes close enough that they can work with it.

In other words, we’re potentially blockers to them getting done what they need to.

There will always be someone who struggles in that moment or maybe has a question, and may file an issue or look us up on the Wagtail Slack. They may even be frustrated because their deadline is dependent on someone else, and who knows how engaged an open source maintainer is at any given time with a library that they haven’t had to touch in a while.

The way we treat people in those moments matters, and a good interaction is some of the best community-building we can engage in.

We can start by having good-enough documentation. Almost all documentation could be better but we can put in the work, talk to our users, and make it as helpful as possible. We can engage with our users in question-answering in the Wagtail Slack, in issues, etc. We can even encourage contributions for features or needs our package doesn’t yet support, but there’s danger here: the stereotypical open source interaction of “it’s open source, go fix it yourself.” Most of us in and around open source have been on the receiving end of this sort of thing at one time or another. It sucks. We do not have to pay it forward.

Instead, we can treat our users with kindness and empathy. And if we can’t manage that in a specific moment—maybe we’re having a bad day, we’re overwhelmed with something and this is one more thing—then I think it’s best to wait. Acknowledge their need, and get back to them when you can be kind and empathetic.

Which brings me briefly to one last thought based on a question Tim had of us panelists: how do you avoid fatigue and burnout? Because those lead to dealing with users without kindness and without empathy. Package maintainer-ship is mostly thankless. You rarely hear from the users who are just getting on with using the package successfully.

I can only answer this for myself, and hope it’s broadly applicable. I write software because I want to solve interesting problems. I want to write useful software in the process, so I write open source software. Built into the idea of open sourcing something is the idea that it could be useful to someone else. The fact that they’re trying to use my software is where I find meaning in what I do. Reminding myself of that helps.