Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.
Many development teams use pull requests as a way to control and socialize the code changes made for a given project. They serve as documentation for the development process as well as a tool to discuss and review the changes. They can also inform future developers about the reasoning behind a particular implementation or coding pattern by including notes about the current state of things when the pull request was originally submitted.
Why should I write a good pull request?
Writing a good, clean pull request description gives us developers a chance to use words (not code) to explain why we are making the change, describe the problem this code is solving, and provide context around why we chose a particular implementation. This information helps speed up the review process, by giving reviewers context before they dig into the meat of the code. It also provides future developers with context, so when they need to make changes in that area of the code, they can understand how we got there and how their new changes might affect the system.
A good pull request description should answer these questions:
Why are we adding this code? What is the problem we are solving?
How did we solve that problem?
What changes were made to solve the issue (infrastructure, new patterns, new models, etc.)?
Where might the user or developer see the solution surfaced (screenshots, application behavior changes)?
A good description that answers these questions will provide the following benefits:
Better, faster code reviews. When they have context, reviewers can better understand the code they are reviewing, so it is easier to provide focused comments and discussions.
Documentation for future developers (including future you). Future developers will be better informed about how their new changes might impact the system because they can look back and be reminded of the state of the project when that old code was written.
The writer is forced to justify their changes. By explaining what was done and why, the developer may find areas where they could further clean up the code to be more robust, readable, organized, tested, etc.
How should I write a good pull request?
We can start with what a bad pull request looks like:
This example has no description, a meaningless title, several commits and lots of file changes. Any guesses on what this code does? I certainly have no idea.
Here’s another bad one:
Here, the words do little to explain what was wrong with the navigation before and what code was added to address this problem. To learn more, the reviewer needs to click through to the ticketing system to read the original story. And there is no indication of how the codebase might have been affected.
Given that same navigation story, a good pull request for the same work might read something like this:
By re-stating the problem, outlining the solution from a high level, a reviewer can quickly understand what changes were made and why. The PR also mentions key files were changed or added and shows the before and after screenshots, providing even more context.
Pull requests should be as short as possible while still answering the what, why and how questions we mentioned above. Put yourself in the reviewer’s shoes, and imagine what information you would want to understand and effectively review the work.
A good description gives the reviewer immediate context. It tells reviewers where they will expect to see changes (what areas of the code) reduces the amount of work the reviewer needs to do to get context. It can show the before and after so the reviewer can easily verify the fixes on their own system (or an acceptance server). And the reviewer should understand why this change is being submitted.
If these seem too complex, the following template (though simple) still gets at the same basic ideas:
In the end, it comes down to a team decision. You want to choose a version that the team is willing to agree on so they’ll be more likely to fill it out.
Pre-review your own pull requests
Another practice we also promote is to “pre-review” your own pull request. After submitting a pull request, you, as the submitter, can go through and add comments in places in the code where you have something that may need further explanation or where some commentary can clarify exactly what’s going on. Of course, we strive for clear self-explanatory code, but occasionally you may want to call something out that is not appropriate for a comment in the code but would help a reviewer understand how and why the code changes are in there.
Write good pull requests!
Hopefully, now you’re motivated to start writing good pull requests and you’ve got the tools to get started.
We’ve seen this process improve team productivity (because code is merged more rapidly) and improve code quality (reviews are better and code ends up with fewer bugs). We hope you see the same improvements on your teams after writing better pull requests.
Illustration by Lo Wheelwright.
Interested in more software development tips and insights? Visit the development section on our blog!