Update: It seems the lovely people at GitHub have added a way to add a pull request template to your repo. Thanks GitHub!
At vzaar, every single piece of code that any developer on my team writes has to be submitted as a pull request. Peer review is very important to us and not only does it help everyone improve as developers, it has also vastly reduced the number of silly mistakes slipping through the net.
Everyone on the team is encouraged to review and merge pull requests, from our junior developers all the way to the most senior developers. However, not all pull requests are the same. We operate a deep, complex system comprising of multiple (5+) Rails applications and several internal gems. There are a lot of moving parts in our platform. So we often have a scenario where someone will assign themselves to a pull request knowing very little about the specific parts of the domain that are being changed.
Now you might say that this in itself is quite risky, and I’d agree. But, we see this risk as worthwhile because the trade off is excellent knowledge sharing across the team, and this is where a good template is important. The pull request code must be good before it’s accepted and merged, but so too must the pull request description. The most important part of our pull requests is describing how you tested the functionality in question.
It’s important to note here that saying something like “the specs pass” is strictly forbidden (unless of course you’re upgrading RSpec itself). Instead, we provide detailed, step-by-step information showing how you tested your own code. This gives the reviewer a detailed test recipe whilst also allowing them to easily think at the right level of detail to properly assess the quality of the pull request.
After more than a year of using this template, it’s proven a huge success and is now part of our normal workflow. Here is the template as Markdown:
#### Summary [mandatory] What does this pull request do in general terms? #### Intended effect [mandatory] What is the expected effect of the pull request? How will the behaviour will be different than before the pull request. #### How I tested [mandatory] What specific steps did you follow to test this code? #### Comments / Potential problems / Questions / Side effects [optional] Are there any questions that need answering before this is merged? Are there any relevant issues outside the scope of this pull request?
To see an example of a real pull request, here is one I submitted for our Ruby API gem: https://github.com/vzaar/vzaar-api-ruby/pull/8
Hopefully this proves useful for you too.