Bystanders Guide to Repository Maintenance

Today's post is about bystanders and open source. We sometimes have anxiety about doing things on "other people's" projects but the thing about open source is that those are not "their" projects, those are "our" projects, and they only exist because people other than their nominated gatekeepers chip in now and then.

Bystanders

A "bystander" is someone who is nearby but not directly involved in something. There is also the "bystander effect" which basically says that as individuals we are more likely to help out with an emergency if we're the only person present. If several others people are also near enough to help, none of us do.

On the open internet it's easy to feel like you're in a crowd. Surely someone else will see this, help here, fix that thing. The thing is, when you're looking at a particular project ... most of the time, there is nobody else around. That one small thing? Is up to you.

Getting Started in Open Source

There are many articles on how to get involved in open source, I've written at least one of them myself, but this is about micrcontributions. The act of giving a moment of attention to every project whose path crosses yours. This post has specific examples that I hope seem approachable - so have a read and then look out for opportunities to lend a little of your skill, time and energy to these open projects that are powered by many small actions by many passing individuals!

Add information to existing discussions

When you search for an error message and find it in an open issue on a project, go ahead and read the discussion thread. Often the answer is here or in a linked pull request (in which case you're about to learn how to build a library from source. Please prepare to open your own pull request if any updates are needed to the installation instructions - most project maintainers aren't installing their projects from fresh on a regular basis so this area of a project can easily get neglected!). If you can, post about the software versions you're using and clarify if any workarounds helped you.

The "me too" posts are tempting but they can really add to maintainer notification fatigue. If you are also experiencing an existing issue, or would also like to see a particular feature implemented, go ahead and use an emoji reaction to indicate this rather than adding an new entry to a thread. Comment if you have new information. Not opinions. Information.

Answer questions

I work in Developer Relations, which requires troubleshooting of any of our products, in any tech stack, with any related dependencies, at any time. This makes me an expert in error messages and suggesting that running the dependency manager command again might help! In fact I think that as developers we can often help one another without any "specialist" knowledge needed. To this end I like to read the first few issues on every project I see and check if there's anything I can help with. Even if I don't know the library at all, "try redirecting stderr to stdout and see if you get any output" can go a long way and "unstick" someone.

It's not your project, and you don't have specific knowledge, but it's likely you have some related knowledge so share it if you do! Even if it's just a "first response" to ask for the error message, what platform they are using ... you have saved the maintainer a little bit of time AND started the clock ticking on waiting for a response. It's more valuable than you can know.

Informal bug report triage

Open source projects grow very unevenly. Usually they start as just one or two people making a thing and sharing it. The early adopters are probably also contributors as well, and that works. Then there's a whole middle size of project which is just ... fine. Quiet, manageable. At the other end of the scale we've got huge, high-profile projects with (hopefully!) a team of maintainers. But before that I see quite a lot of projects that have a LOT of users, of varying levels, and a very small number of maintainers who have other jobs and commitments. At all stages, but especially this last one, a little help goes a really long way. It's very easy for maintainers to be so swamped by issue chatter that they can't ever get out of the backlog of communications to work on something, and without being negative at all, bulk handling of support tickets may not be the best use the universe could make of their time and skills!

To help with this situation, take another look at the issue list, but this time dive a little deeper and look at reported issues that genuinely seem like bugs. You're going to triage by looking at the bug report, trying to reproduce the bug on your system, and then reporting whether you can reproduce or not (including your system information). You get bonus points if you can also write a test for the failure, document a workaround, or even offer a patch :)

For example, I maintain a project but I'm a Linux user and my co-maintainer has a mac. The Windows bugs are going to be there for a long time unless someone else chimes in - just a "looks OK for me on Windows 10" would help us a lot. Many projects also use a tag like "help wanted" for issues where another pair of hands would be especially welcome so if you have a project you'd like to support you can look out for those as an easy way to lend a hand.

Be the myth you want to see in the world

It's a common misconception that open source software is made by noble individuals for the good of the world. In fact, it's cobbled together from a whole raft of passing comments, code copied from another website, and one-line contributions from random and unknown humans. Open source is a movement, and it is strong when we all participate in one way or another. You don't need to become a full-time maintainer to make a difference; make microcontributions part of your normal practice and be part of the strong future of open source. Even the smallest contributions help every project to inch forward, and lets the maintainers know there is someone out there!


Also published on Medium.

Leave a Reply

Please use [code] and [/code] around any source code you wish to share.

This site uses Akismet to reduce spam. Learn how your comment data is processed.