At The Neon Project we care about our internal processes: we believe they’re important, we design them meticulously, we use them, and we improve them as we learn from their performance in the real world.
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 since, many times, code that seems easy to understand for the author is not as clear for the rest of the team. Everyone involved in the code review learns: learn how to give feedback, learn how your partners think and write code & learn technical details.
To 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. After reviewing the Dev.to Github repository and seeing some pull requests, I 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 it is created.
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 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 PR. This part is essential for the person who reviews the code to know, in one pass and briefly, what to expect in the code.
Screenshots (if there are changes of UI): one of the problems of the PR that have visual changes is to know what has changed or what is the final result. In general, the process to execute the code locally and see it won't be 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 and Imgur to upload them.
(optional) a gif that describes how it makes you feel: 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 and thus are able to deploy code more often 🚀
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 when a contributor needs to have a PR checked, can assign a reviewer automatically and offers a series of very interesting analytics to know, for example, the average time needed to make reviews or how many took more than 8 hours. And it's free!
That's it, folks. So, how's your code review process? Any advice on how to improve ours?