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.
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.
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.
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.
However, this pull request template example is complex. Filing every section will take away precious time from your developers.
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?
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.
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.