Creating a nice pull request

July 24, 2015

Working in a team requires more than development skills. You need to push yourself harder and try to imagine what your fellow needs. On a team there are pull requests. Here is the GitHub's definition:

Pull requests let you tell others about changes you've pushed to a repository on GitHub. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.

Seems easy, right? Well... that is not true for all teams. Sometimes I see pull requests without information.

Asking a review

To create a good pull request I will give you some useful advices (in my opinion):

A short title with a meaningful overview of what are you trying to introduce in the codebase. This title could also contains a code for reference.
Descriptions are awesome. With a description you could explain a little more your changes, give a substantiation for a specific solution, advice or warning about something. Provide context, your mate possibly doesn't know anything about your tasks. Remember: your teammates are busy too, the more information you give, the less time you consume of them.
Mention the reviewers. Don't be anxious: pull requests are async. They will take a look only when found some time to do it.
Answer in the pull request, always. If you talk by private messages another fellow will not know about that talk. A response is useful for everyone. Also serves as a registry.
Don't take a correction or suggestion as an offence. I believe every developer in the world want to work in a wonderful codebase. Corrections and suggestions are to keep or improve that.

Making a review

Be polite, always.
Sometimes a quick example in pseudo code could be more valuable than a thousand words.
Ask for more information if you can't understand the whole meaning of a change.
We know bad code happens but wait: there is awesome code too. Give your fellow a congratulation when achieves something valuable or that deserves a recognition. A proper emoticon could help too.

Conclusion

A code review is useful for anyone. Yes, tech leads can't know everything. Pull requests and code reviews serves to everyone for different reasons:

You can let everyone know about your changes.
You can learn from others.
Others can learn from you.
The codebase grows solid and better.

Finally remember that you are the owner of the code introduced by a pull request. When sometimes goes wrong, you are responsible.

. . .

Some time ago I read a really good post of Mark Seemann. I strongly recommend you to read it because he mention important things to take care on creating a pull request.

Thanks to Andrés for all his wisdom.