Tom MacWright

How to maintain a bunch of open source projects

Even after shedding my open source responsibilities at Mapbox, leaving a few major projects, and archiving old GitHub repositories, I still have a pretty significant set of open source projects to maintain and garden. I’ve settled into a decent rhythm doing it. Here are some of the key points for how.

Use a little automation for releases

I use standard-version for all of my open source projects, and write all my commit messages in a particular way. You might want to use something more exotic, like semantic-release, or less fancy, like a checklist.

The point is that you’ll return to a project in the medium-far future, want to make a small change and roll a release, and you won’t remember how you did it the last time. Tools like standard-version help with this.

I don’t automate the creation of projects with scaffolding. Typing is not the problem. You’re going to do a lot more releasing software than starting projects, so automate releases.

Know the parti pris

I like the architectural jargon ‘parti pris’ for the central concept of a design. Or, in a less highbrow sense, remembering simply what’s the punchline of the joke.

Projects should have a driving force. A logging framework might aim to support ‘just about everything’, or it might be ‘super fast’. The one that supports everything might reject a PR that makes it faster at the cost of universality. The fast one might reject a PR that adds configurability but makes it slower.

Basically, what’s the point. Try to remember it. Writing it down in a sentence or two will keep it in your head and help everyone understand it. It’s remarkably common for projects to simply lose the narrative as time goes on. Nobody wants bloat and complexity, but if most PRs add code (and they do) and you feel bad rejecting PRs (and I do), then that’s what you get.

Good-enough issue & PR tracking

Here’s the trick:

  1. Click on ‘Issues’ or ‘Pull requests’ in the GitHub navigation.
  2. The default search query will include something like ‘author:tmcw’, with your username instead of tmcw.
  3. Double-click that and replace it with @tmcw, where ‘tmcw’ is your username.
  4. Now you have a list of issues or pull requests in your repos, instead of issues or pull requests you opened.

There are fancier ways to get an overview of your responsibilities, but this hack is quick and built-in.

Gradually blend individual with community structure

Successful large open source projects tend to have a lot of signals that they’re owned and maintained by a community, as opposed to a person. For example, they’ll have their own GitHub organizations rather than being nested under a personal account. They’ll have issue templates and contributing guides. They might use npm orgs to manage permissions for publishing.

These are solid structures for community projects, but if you build them, the community doesn’t necessarily come. At the early stages, collaboration is a cost, not an advantage. Building the infrastructure for collaboration takes time, and that time might be better spent just building the project instead.

Say no

You need to say no when people file imprecise bug reports. Or ask for features that don’t fit the project. Or want you to help them install your JavaScript module on their Amiga 64 system. Or bug you for support via email. It’s tempting to be nice but it’ll drain you.

March 28, 2019  @tmcw