A few years ago, GitHub introduced pull request templates to help streamline the software development process as a team. They are files that allow developers to write a pull request description with a pre-defined structure that will help their teammates get a better understanding of what they did.
They are very useful because they help contextualize the code review process. After all, it’s a very time consuming process for devs, and a very hard one for non-technical stakeholders who bring a more holistic opinion about the code that will potentially get merged into production.
The absence of a pull request description is very painful, picture this: You are cooking a complicated but exquisite meal with your friends. One of your friends, confident of his culinary abilities, hands you a pan with a simmering concoction.He claims it’s the secret ingredient to the dish. You taste it and you’re left perplexed. You ask him about the recipe, and you receive a dreaded “I can’t give you the recipe” message. You see a bunch of ingredients, with no labels or explanations, and you’re left lost.
This is the same kind of frustration that a developer feels when he sees a “No description” message in a pull request.
Pull request templates solve this problem by enforcing developers to contextualize the code review process. However, having an overly complicated pull request template will reduce developer velocity.
Unpacking a Standard Pull Request Template Example
What’s the ideal pull request template example? Let’s take a look at two examples and boil it down to a few fundamental principles.
This is the canonical pull request template example (a shorter version of the one we have on our repo). In our opinion this is the minimum threshold of information that a pull request description should include.
<!-- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change. -->
## Type of change
<!-- Please delete options that are not relevant or write your own. -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Chore: cleanup/renaming, etc
- [ ] RFC
Despite the fact that this pull request example forces the author to write a description and check a box that states which type of change this proposed change inserts to the codebase, we could do much better.
Let’s explore the idea of adding more information to a pull request template.
The Hidden Costs of Complexity
A context-rich but very complex pull request template example impacts the productivity of the team negatively.
In this final pull request template example we add a lot of steps, and they’re all there for a very good reason.
## Summary
<!-- Provide a concise summary "Why are the changes needed"?
Include any relevant links, such as Jira tickets, Slack discussions,
or design documents. -->
## Changes Made
<!-- Describe the specific changes that have been made in this pull
request. Provide details on the approach taken to address the problem
and any notable implementation details. -->
## Type of change
<!-- Please delete options that are not relevant or write your own. -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Chore: cleanup/renaming, etc
- [ ] RFC
## Checklist
- [ ] I have added comments to code in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] Any dependent changes have been merged and published in downstream modules
<!-- Optional Sections -->
<details>
<summary><strong>Expand for optional sections</strong></summary>
## Screenshots
<!-- If the changes are visual, including screenshots or GIFs can
help reviewers understand them more easily. -->
## Related issues
<!-- A link to any related issues or bugs that the pull request
addresses, connecting the code's context with the problem it
solves. -->
## Testing instructions
<!-- Instructions on how to test the changes made in the pull
request, helping reviewers validate the code. -->
## Special notes for your reviewer
<!-- If there are any specific instructions or considerations you
want to highlight for the reviewer, include them in this section. -->
</details>
<!-- End of Optional Sections -->
However, this pull request template example is complex. Filing every section will take away precious time from your developers.
Advocating for Minimalism
The best template is the simplest one. The simplest one that doesn’t leave critical information out.
Is there a way to get the amount of context from the second pull request template example, with the time investment of the first pull request template example?
Transitioning from Complexity to Simplicity
Let’s go back to the last pull request template example. Every single element there is in place for a very good reason but it will be very time consuming for the developers in your team to do this every single time they send a pull request.
Screenshots might sound like a very trivial thing to do. But most of the time what you actually need is a video (perhaps renaming this section is an opportunity of improvement for such pull request template example). A video showing the application flow(s) being affected by the pull request. Which not only involves a context switch but also setting up the screen recording in a way that will make the pull request author explain what was changed. You also eventually end up linking to Figma.
Testing instructions might also be underrated. “I’ll write one or two sentences and that will be enough to instruct the reviewer”. It’s more than that. What’s the edge case to test? Is there one in the first place? How can you execute a non-obvious step in the process? Is there a certain username you need to try this with? What about screen sizes? As much as you have a well-placed TDD process, no one dares (and no one should) merge a pull request without a manual testing process.
The related issues section is very interesting. Out of the new sections introduced in this pull request template example it is the most useful one. It is the largest context provider. It gives information about previous approaches that have both succeeded and failed, what provides value to a user and what doesn’t, and how has the business logic been historically affected. This information can live not only in pull requests but also in Slack message threads, in project management tickets in systems such as Jira and Linear; and also in documentation systems such as Notion and Confluence. Most frequently, you either end up in a Zoom call (less than ideal, this is the biggest reducer of developer velocity of all) or linking to a piece of documentation, or discussion.
Our GitHub application can help your team automating the retrieval of these related pieces of information.
Conclusion
Pull Request templates are necessary but if you overcomplicate them you will reduce your team’s developer velocity. Keep it as simple as possible. We suggest using the first pull request template example or Watermelon’s pull request template example, and enrich such pull requests with our GitHub application.
Top comments (0)