Before you write a patch, write an email

Apr 27, 2012 • Andy • Open source • collaboration, patches, WISCY

« What if news stories were written like resumes? Rethink the post-interview thank you note »

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.

7 responses

With patches, my usual modus operandi is: if the work involved takes less than one hour(ish), I go ahead and do it. For the time invested, I find such a “show, don’t tell” approach more efficient. And if the “show” part involves documentation and tests thrown in, all the better. But, and there I totally agree with you, I always, always keep in mind that the maintainer might decide not to accept the new feature, or may want it behaving differently, or may just never answer back.

And for any work that takes more time than that, it’s indeed a very good idea to contact the maintainers first. Between GitHub comments, IRC, RT, blogs and emails, it’s a fairly easy thing to do and, yeah, has been known to save time and gnashing of teeth on all sides. The only danger that is attached to doing this is that, more often than not, one ends up getting a co-maint bit on the project. The horror. :-)

Yanick – April 27th, 2012
First, I don’t think you should feel bad about saying “No” for whatever reason. If it doesn’t fit, then it just doesn’t fit.

It’s easier than ever before for someone to fork a project and keep their own personal version of it and keep it up to date with the main project.

I’d like to point out however, that it’s a toss-up what a particular maintainer wants as far as submissions. There are just as many, or possibly even more, posts like this one advocating the opposite idea. That is, “just submit a patch”.

Perhaps this is a downside to git (and github) making it so easy to fork and submit pull requests …

harleypig – April 28th, 2012
I fundamentally, and vehemently disagree. NEVER ask permission. Let me list my reasoning:

#1. You vastly underestimate how horrible an “e-mail” is… it is shouting into a well… there may never be an answer, it may be in a spam filter, the author may not care, he may think it was so stupid he didn’t respond. I can think of very few things as demoralizing as emails… you don’t know if it arrives, you don’t know if the person cares.

#2. It destroys the fundamental value of distributed version control. There should NEVER be any blocker to a person starting development, they should just start hacking. I even think that if they have an idea, they shouldn’t bother digging through the list, digging through contribution guidelines, etc – they should solve their problem, and solve it well – learn how to contribute after the work is done. Let us leave bureaucratic business to the bureaucrats.

#3. You might not accept that patch, but they scratched their own itch, and they should publish their little patch (even if YOU don’t want it), and the community can decide if it is useful. In the vim community, for years certain patches have lingered outside of the mainline – but over time, they slowly did get accepted because while the maintainer didn’t want them, the community did.

#4. What is the “added value” of jumping through the hoops you have laid out – I see none. I don’t think the person should be demoralized if you reject the patch, maybe they are wildly smarter than you, and you bouncing the patch was your own shortsightedness – but as long as they do the work, and post it publicly, maybe the community is smarter than the maintainer.

Robert Melton – April 30th, 2012
You sound pretty angry about my posting, but I don’t think I’m saying the things that you think I am. Maybe I wasn’t clear in my writing. Maybe you missed some parts of the article. Either way, I think we pretty much agree.

You said: “NEVER ask permission” and I agree 100%. Nowhere do I suggest asking permission. I only suggest that collaborating upfront may have value for all, and it’s a low-cost bit of research that can save hours of work.

Yes, there may never be an answer to your email. I agree that it’s discouraging. From the article: “Or maybe you’ll get no reply to your email at all, which tells you your work will probably be ignored anyway.” Sending email and hearing nothing back only reinforces the importance of what you want to do.

You say “There should NEVER be any blocker to a person starting development,” and again, I have never suggested that anything block your development. I do suggest that sometimes the best way to start development is to not yet write code. The WISCY link in the article is illuminating.

You say “You might not accept that patch, but they scratched their own itch,” and I agree. From the article: “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.”

You talk about “jumping through the hoops you have laid out”. I don’t see “hoops”. I see sending an email, and doing a bit of reading to find out what others on the project are doing. That’s good, low-cost research to save you time.

You ask about the added value. The value is in knowing upfront if your code is something that’s likely to get accepted into the project. Even bigger, from the article: “Maybe you’ll find that what you’re suggesting is already done and ready for the next release.”

You state “It destroys the fundamental value of distributed version control.” I think that collaborating up front is only enhanced by distributed VCS. Perhaps what you’ll find in your communication with the rest of the project is that someone on the team already has a branch on her fork on GitHub and is looking for help with it.

Open source is all about the code, and it’s all about communication. Talking to the rest of the project only has the opportunity to increase the collaboration and value of the coding to be done. And if it winds up that nobody else is wanting to talk about it, then you can carry on anyway.

Andy – April 30th, 2012
I think you misunderstood the point too..

I recently got a massive patch with a new feature for a project I run. I wanted the feature, but it was put together quite badly and there was no way I could have accepted it in it’s state.

I actually got the patch because said person was stuck on something and asked for help.

A correct implementation would have been possible if I could have guided him. This guy was obviously not very experienced.

Evert Pot – April 30th, 2012
I think it gets you LESS developers, wastes YOUR time, and makes the community as a whole more talk, less walk.

You are setting your up for an onslaught of worthless emails from people who will NEVER DO ANYTHING. I have dealt with hundreds of emails from “future contributors” and it is an insane waste of time, most of them are more interested in talking, less interested in coding.

I think the concept of pre-work communication is terrible and steals time from people who are 100% guarantied to contribute usefully (the maintainer) and gives it to people who have what… a sub 1% … 5% at best chance of doing useful work? It is a terrible worthless exchange rate. Code is the cover charge, it is the price you pay before anyone should waste a single second listening to you…

I think your idea converts good work (maintainer work) into crap work (random guy who might someday do something on your project and will probably do it poorly)… let him take the risk, spend the time, do the work – there are dozens of him, only one of you.

Talk is TOO cheap, FAR cheaper than code, make them pay the cover charge. The cover charge shows mutual respect and gives you something concrete to discuss.

Robert Melton – April 30th, 2012
I disagree, I put forth the hypothesis that if he had come to you earlier, you would have exactly nothing, not one line of code.

You guys would have got bogged down in discussing implementation strategies, you would show off your superiority, he would feel embarrassed by his own ignorance… at the end of the day he probably wouldn’t have coded anything, just given up demoralized. Not because you are a mean guy, but because it is a skill mismatch.

Because he worked on his own, he created something concrete, he paid the cost to be worth spending your time on – and now you have a code base you can refactor and iterate on, or let him do that with some sage advise, and now because he is actually invested (in code and mindshare) he will take the time to make those improvements.

Him not coming to you was the best possible thing.

Robert Melton – April 30th, 2012

« What if news stories were written like resumes? Rethink the post-interview thank you note »