A plea for better open source etiquette

Update: this post kicked off a lively debate over at HackerNews.

As a result of doing consulting, I’ve been hopping between a large number of OSS tools and libraries for the past few years. At some point, I decided to start giving back (after taking so so much) – something that GitHub has made incredibly easy, at least in the technical sense. For the most part, my interaction with maintainers has been very professional, effective and pleasant, but has also gotten under my skin enough times for me to want to post about it.

So, a plea to the OSS maintainers out there.

You would make my coding life much much happier, if:

1) You could always have the courtesy to acknowledge the bug or pull request I’ve submitted.

By the time you’ve got an issue notification from GitHub, I have already:

  • Hit and investigated a problem with your project
  • Trawled the forums/Stackoverflow/bug tracker for a fix
  • Documented the bug, context, testcase etc

For a pull request (PR), I’ve had to do even more legwork, ie:

  • Slug through your (not always the most obvious in the world) code
  • Figure out your coding conventions
  • Create a working fix
  • Update or write new tests
  • Update docs
  • Document the PR

So, if I haven’t provided enough context or information or test coverage, say so. I’ve invested time already, I don’t mind spending a bit more to get the change over the line.

If you’re no longer maintaining the project, say so. That’s cool too, perhaps I can hopefully find somebody who has continued your work.

If you have crunch time in your day job, are moving house and going to your gran’s for 3 weeks, just set the expectation that you won’t have time to look at this for a month.

If you think that the proposed change doesn’t fit the direction of the project, or the bugfix is in the ‘nice to have’ pile on your backlog, say so. I might not have gotten the result that I wanted, but at least I would have closure.

In the very least, say SOMETHING, so I don’t feel angry and annoyed that I spent all this time and effort for nothing.

Besides, if you or your company are keen to benefit from community contributions, a bunch of unacknowledged year-old PRs lying around probably isn’t the best way to achieve that.

2) You could merge tiny changes quickly

The killer GitHub + Travis combo leaves little excuse for slow merging of very small, safe changes (ie small refactorings or documentation typos) – I’ve been able to accept changes during my train commute on my phone over a dodgy 3G connection. Nowadays, before any non-trivial contribution to a new project, I tend to raise a tiny PR first. The time it takes for this PR to be merged informs my decision on whether or not to expend effort on the larger change.

3) You could apply a two-step process for reviewing bigger changes

If an issue needs time to investigate or to analyse, you could acknowledge it first (see 1)) and set expectations on when the investigation/analysis would take place. Then take the time you need. This way, you don’t leave the submitter in limbo.

4) You would not forget to thank people for their time and effort.

It’s easy to do and does make a difference.

Yes, I know, most maintainers do open source in their free time, but the same is true for the submitters. Just some simple changes could make the experience that bit more fun for everyone.


  1. Fact: They aren’t there to make your life easier or better. Accept or be unhappy.

  2. @SteveC:
    It’s not about making someone’s life easier or better, it’s about fostering an environment where people *want* to help you out in your open source project. Which is, supposedly, something that OS maintainers want. So, the reverse of your statement is true, too: Supporters aren’t there to make your life easier or better. Accept (and be nice) or reject (and risk losing supportive environments).

    It’s something the open source community has grappled with for a long time, and comments like yours don’t really help!

  3. +1 to what Jake wrote. Also, on a lot of the medium-to-large projects, the upstream maintainers are often not volunteers — they are sometimes salaried developers whose job is that project, and even when they’re not, they often still have some interest in the code beyond just enjoying hacking on it. Not that volunteers can’t be responsive too, in the way that Jake suggests.

    I think the dynamic is often this:

    Upstream developer sees a PR, thinks “No point making a placeholder response now — I’ll have time to look at it later this week / on the weekend / whatever.” Then that time doesn’t materialize. Meanwhile, they’ve let it go so long they feel a little bit embarrassed to be only responding so late, so they want any response they make to be substantive (rather than just a “thank you, we’ll look at it as soon as we can”). And what Jake is saying is that quick responses are still useful. If you take five minutes to review and say “This looks useful” or “This was discussed in the archives, here’s the SIP to search for”, even that’s enough to let the submitter know that they’ve reached the right people. You do that easy part first (see Jake’s point 3 above) and do the hard stuff later, after letting the person know you’re engaged.

    (Full disclosure: I’ve been guilty of the sins Jake describes. He’s still right, though, IMHO.)

  4. One thing you could do is to start measuring the time to respond to a contribution, we do this in Ubuntu:


    That way it’s clear to everyone (the submitters AND the reviewers) where a certain patch stands in relation to the others and what the average time to a response is. Measuring this stuff is really the only way you can scale.

  5. You could make my blog-reading life much easier if you told me what a “PR” was at the moment when you introduced the term.

    1. Jake Benilov · ·

      Oops, had it defined but then edited that bit out. Fixed… thanks.

  6. More projects should look at and adopt the Web Hypertext Application Technology Working Group (WHATWG) HTML Living Standard page (http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#scripting-0).

    You can see status annotations in the left margins that allow you to go to extended/extra information on each section. If you have comments/questions on a section, you can use the widget at the bottom right (it says “Click the location of the error to select it, then type your message here:”) to submit a review comment.

    e.g. of possible status annotation states are:

    “Idea; yet to be specified — the section is a placeholder.

    First draft — An early stage.

    Working draft — An early stage, but more mature than just “first draft”.

    Last call for comments — The section is nearly done, but there may be feedback still to be processed.
    Send feedback sooner rather than later, or it might be too late.

    Awaiting implementation feedback — The section is basically done, but might change in response to feedback from implementors.
    Major changes are unlikely past this point unless it is found that the feature, as specified, really doesn’t work well.

    Implemented and widely deployed — the feature is specified and complete.
    Once a section is interoperably implemented, it’s quite stable and unlikely to change significantly.
    Any changes to such a section would most likely only be editorial in nature, particularly if the feature is already in widespread use.

    There are also two special states:

    Being edited right now — the section is in high flux and is actively being edited.
    Contact Hixie on IRC if you have immediate feedback.
    (This state is not used often.)

    Being considered for removal — for one reason or another, the section is being considered for removal.
    Send feedback soon to help with the decision.”

    Here’s something possible you can do in the future using annotations: e.g. “Some text in view has voice data/images/gifs/videos/examples/diagrams/extra detail/requests for additions associated with it. Highlight text that has them? See them? Fulfill requests for points/bounties?”

%d bloggers like this: