At The Neon Project, we care about our internal processes. We believe they’re important and we design them meticulously. We use them, and, as we learn from their performance in the real world, we improve them.
One of the most important processes when developing software is code review, where at least one teammate will review your code. This process improves the quality of the code. Many times, authors understand their own code but it is not as clear for the rest of the team. Doing code reviews has many benefits: First, everyone involved in the code review learns through PRs. In addition, reviewers learn how to give feedback. Last, authors learn how their partners think. Overall, the team learns better ways of writing code and technical details.
This said, how can we make the code review process as easy and quick as possible? The more context we give our colleagues about what we have done and why, the better.
Discovering PR templates
The inspiration came from reviewing the Dev.to Github repository and seeing some pull requests. We thought there was a way to improve our code review process in The Neon Project: using templates for pull requests.
A pull request template is, basically, a file containing markdown text that is added to your pull request description automatically when you create it.
The file must have the name pull_request_template.md. In our case, this file is in a hidden folder named .github, but you can put it wherever you want (more information about Github pull request templates here).
Our PR template
Our template consists of the following parts:
- A reminder: As we use Jira for project management, a very useful feature is to link a PR to a Jira issue by adding the issue code to the PR title. This way we can see its status from Jira
- Type of PR: Consists of 3 checkboxes, indicating whether the pull request is a bugfix, a new feature or a refactor.
- Description: A brief description of what we can expect from the PR. This part is essential for the person who reviews the code. It helps them know, in one pass and quickly, what to expect in the code.
- Screenshots (if there are changes of UI): One of the problems of the PRs that have visual changes is to know what has changed or what the final result is. An alternative for reviewers is to execute the code locally. This is not fast: the person will have to download the code changes in their machine, have the environment configured, etc. A few simple photos and/or videos will save a lot of time to see what’s new. Personally, I use [macOS screenshots](https://support.apple.com/en-us/HT201361) and [Imgur](http://imgur.com) to upload them.
- A gif that describes how the PR makes you feel (optional): Because there’s always a good reason to put gifs, right? 🤓
In this simple way, we improve the code review process: more information and context so that code reviewers can understand quickly what they are going to review. This, in the end, means we are able to deploy code more often 🚀
One more thing…
After the announcement that Github has acquired Pull Panda, we have integrated it into our process and we are very satisfied! For those who don’t know it, Pull Panda allows you to remember through Slack, another one of the tools we use at The Neon Project, when a contributor needs to have a PR checked. Furthermore, it can assign a reviewer automatically and offers a series of very interesting analytics. For example, the average time needed to make reviews or how many took more than 8 hours. Bonus points… it’s free!