Before you write a patch, write an email


(Originally posted to my non-Perl blog)

I often get surprise patches in my projects from people I’ve never heard from. I’m not talking about things like fixing typos, or fixing a bug in the bug tracker. I’m talking about new features, handed over fully-formed. Unfortunately, it’s sometimes the case that the patch doesn’t fit the project, or where the project is going. I feel bad turning down these changes, but it’s what I have to do.

Sometimes it feels like they’re trying to do their best to make the patch a surprise, sort of like working hard to buy your mom an awesome birthday present without her knowing about it. But in the case of contributing to a project, surprise isn’t a good thing. Talking to the project first doesn’t take away from the value of what you’re trying to do. This talking up front may even turn up a better way to do what you want.

There’s nothing wrong with collaborating with others to plan work to be done. In our day-to-day jobs, when management, clients and users push us to start construction of a project before requirements are complete, it’s called WISCY, or Why Isn’t Someone Coding Yet? As programmers, it’s our job to push back against this tendency to avoid wasted work. Sometimes this means pushing back against users, and sometimes it means pushing back against ourselves.

I’m not suggesting that would-be contributors go through some sort of annoying process, filling out online forms to justify their wants. I’m just talking about a simple email. I know that we want to get to the fun part of coding, but it makes sense to spend a few minutes to drop a quick note: “Hey, I love project Foo, and I was thinking about adding a switch to do X.” You’re sure to get back a “Sounds great! Love to have it!” or a “No, thanks, we’ve thought about that and decided not to do that”. Maybe you’ll find that what you’re suggesting is already done and ready for the next release. Or maybe you’ll get no reply to your email at all, which tells you your work will probably be ignored anyway.

I’m not suggesting that you shouldn’t modify code for your own purposes. That’s part of the beauty of using open source. If you need to add a feature for yourself, go ahead. But if your goal is to contribute to the project as well as scratching your own itch, it only makes sense to start with communication.

Communication starts with understanding how the project works. The docs probably include something about the development process the project uses. While you’re at it, join the project’s mailing list and read the last few dozen messages in the archive. I can’t tell you how many times I’ve answered a question or patch from someone when I’ve said the same thing to someone else a week earlier.

Next time you have an idea to contribute a change to an open source project, let someone know what you’re thinking first. Find out if your patch is something the project wants. Find out what the preferred process for submitting changes is. Save yourself from wasted time.

We want your collaboration! We want you your help! Just talk to us first.


As someone whose patch to ack was recently warnocked and is in free-fall to the bottom of the patch request queue: I really don't mind. I had an itch that scratched, and forking the project from github to fix it for my own usage scenario comes natural.

Until now, I'd have done nothing different if I had asked beforehand if the feature would have been accepted and would have heard back that it wouldn't. Either way, I'd then polish my own personal patch: you want to keep it as maintainable as possible, even more so if you have to shepherd it for your own private use.

So in this case I could have asked before I started, wait for an answer, loose the focus of the current yak-shaving session and in the meantime might have found a clumsy work-around. No one would be better of.

The beauty of github is that it allows for this kind of drive-by patches. I understand that you dislike turning down patch requests and that it is harder to turn down fully fleshed out features, but I got the feeling that you think working code is more work then asking if it would be useful for the project as a whole. I think that's an important sentiment, especially for a project lead of an FOSS project, but I think you are mistaken at least in some of the cases.

Just take a look at the ack queue. My guess is that most of the submitted patches are still chugging along happily on their creators machines and doing exactly what they were intended to do: satisfy the need of the one person hacking it up.

That said: I really appreciate the job you are doing as maintainer of ack (the only project of yours with which I had minor contact). If you had accepted all the nifty things people asked you to pull, the code would have been a mess ;)

You scared me when I read this. I thought that you'd sent something that I hadn't replied to, but if you're talking about this patch then it's definitely being discussed. When you say "Warnocked", I took that to mean you didn't hear anything back, and I try to reply to everything.

Agreed 100% on the "do it for yourself." I hope it was clear that I wasn't saying "Don't bother modifying something for yourself. And yeah, it's pretty slick the way Github tracks all that. I think I can identify about half of the forks that people have going as things I didn't want to put in ack itself. I try to check the ack network to see what people are doing, because there are sometimes things that people have done but didn't tell me about, and I have pulled in things like that before.

My article wasn't just about ack, of course. I heard mail from someone today who said it's a problem he deals with, too. I've myself been the one who has created a patch to a project that has gone nowhere, and I've kicked myself for not asking first. :-)

I usually just open an issue in GitHub, being sure to make it clear that a) this is a feature request, not a bug report, and b) I'm willing to do the work (not asking the author(s) to do it for me). This has always worked well for me.

The only problems are when the project isn't on GitHub, or the author has the issues feature turned off for the project. Then I have to send an email, or open a CPAN RT ticket, but I much prefer the GitHub issue in terms of interface, visibility, etc.

Leave a comment

Job hunting for programmers

Land the Tech Job You Love, Andy Lester's guide to job hunting for programmers and other technical professionals, is available in PDF, ePub and .mobi formats, all DRM-free, as well as good old-fashioned paper.