Pull request etiquette

CPAN Lotterygithubpull requestscommunityetiquette Wed 31 December 2014

This is a collection of thoughts related to the etiquette of making pull requests. This is written with the CPAN pull request challenge in mind, but hopefully much of it applies more generally. These are just my thoughts, merged with guidelines found online, hastily written up. Please add and refine based on your experience.

Thanks to GENEHACK and Chris Salch for updates.

Be polite

People share their code for all sorts of reasons, but there's generally some aspect of "Here's this code I created, I hope it's useful for someone". We've all got different levels of experience and skill; treat everyone else with respect.

Your pull request might be the author's first experience with the open source culture. Imagine your younger sister or brother released their first piece of open source and got their first pull request. What kind of experience would you want for them? Positive, encouraging, and above all, polite?

Keep changes small

The larger and hairier a pull request, the less likely the author is to act on it quickly, particularly if (s)he doesn't know you. Which leads us on to ...

It doesn't all have to go in one pull request

If there are several things you'd like to contribute, then consider multiple pull requests, especially if the changes are unrelated. Earn your spurs with the first pull request.

Not all changes are equal

You should be aware that the maintainer might be a bit touchy if you start proposing backwards incompatible changes to the API for the module, or completing re-architecting the internals.

We're not saying you shouldn't go for it, if you really think that's the right thing to do, but be sensitive on how you approach it. Bull. China shop. You get the picture.

Follow the repo's conventions

When making changes, you should follow the coding conventions already established, even if the author doesn't follow more widely established practices. It's their code; and as the saying goes: when in Rome you should do as the Romans do.

Some repos have a CONTRIBUTING or CONTRIBUTING.md file, with guidelines for how to contribute. Check to see whether the project has such a file.

Do the whole change

If you're adding a new method to a class, you should not only add the code, but also:

Try not to generate work for the author, having to finish off your change.

Make atomic changes

If you're making two specific changes, for example adding two new methods, then add them in separate commits. Each commit should cover everything related to the change, as outlined in the previous point.

It's easy to forget to update the MANIFEST, or some other part of a CPAN distribution. Learn about git commit --amend.

When in doubt, check with the current maintainer

If you're not sure about anything, or if you really want to submit a big hairy change, then get in touch with the author / maintainer first. You may find they have work already in progress, or other ideas that you could take on board.

Or they may have a good reason for not wanting to add the method you're working on. You may save yourself some time, if nothing else.

A good way to start this conversation is raising a ticket for the changes you're thinking of making. Github issues encourage a conversational approach to tickets.

comments powered by Disqus