One thing that I often struggle with when managing my open source projects is handling patches.

Because of the nature of OSS projects, anyone can submit a patch that adds a new feature or makes changes to existing functionality. This is very powerful as it allows anyone to work on and improve the project. However, it can often put quite a large burden on the people coordinating the project if the patch has been badly thought out (especially if it’s only one person managing the project).

The vast majority (but not all) of patches that I receive are submitted out of the blue and are aimed at solving a single problem for the individual who submitted a patch. This may involve fixing a bug that they’ve run into or adding a feature that makes something easier for them. Unfortunately, these sort of patches are very often *too* focused – they don’t take into account the big picture and may have side effects on the codebase of which the author may not be aware.

This is, of course, completely understandable – it’s difficult to jump into a project and add/fix features if you’re not already familiar with the codebase.

When I decline a patch, I always try to explain to the author why I declined it, what I consider to be the problem and how it could be improved. I do feel bad when I do this – it’s clear that a lot of effort goes into these patches. Occasionally, the author will then engage me in conversation about improving the patch and may even submit a fixed version, but a lot of the time I never hear anything back.

This could be avoided if there was better communication to start with. If you’re considering submitting a patch to an OSS project, then I think the most important thing to do is first to engage with the project developers to get their opinions on the problem you’re trying to solve.

Whether this is through mailing lists, IM, or even Twitter, first discuss the issue with the project developers. They will probably be able to provide additional context and useful information about the problem which will result in a higher quality patch (which is more likely to be applied).

This way, things are likely to be much more pleasant for both the submitter and the maintainer – a higher quality patch means the maintainer has to spend less time reviewing it, and the submitter won’t have wasted his time writing a patch that ends up being declined.

Communication is the key.

*Edit*: Victor made a good point in the comments that sometimes an exploritory patch is used as the starting point of a conversation, which is a great approach. After the details have been worked out, the patch can be implemented fully with tests and incorporating any feedback from the discussion.