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.