_This was originally published here_
Why is a proper code review process so important?
Developers spend 30% of their time doing code review. This makes PR review the main bottleneck for DORA metrics. However this bottleneck is a necessary evil, because fixing errors in production is even more costly both for the productivity of developers and their team morale.
In this blog post, we will explore the best practices for using GitHub for code review.
Have a proper branching model
By default this should be Gitflow or GitHub Flow, which we have compared in a previous blog post.
The general idea here is to be thorough about how your team is using GitHub for code review. Regardless of whether you’re going to have a develop branch between the main branch and the branches where work is done locally, a proper branching model for properly using GitHub for code review must:
Create your own branches and have them follow the whole cycle of a branch (creation, activation, merge, and deletion, which is an optional step).
Following a proper branch naming convention. This means describing if a branch is a feature, bugfix, hotfix, or enhancement. Ideally followed by the project management ticket associated to it followed by an imperative phrase (eg: “fix sidebar navigation”). A few examples in one of our repositories below.
‍
PRs should be self-sufficient tasks
A common failure mode is to make gigantic PRs. This is very common at FAANG companies, and that’s why they use a unique approach called stacked PRs. While we think this is a very interesting approach to fix this particular failure in the GitHub for code review process, it’s a solution to a problem that shouldn’t exist in the first place.
‍
By default, Pull Requests should be self-sufficent tasks. Using a solution to stack PRs while using GitHub for code review as you already normally do, is a huge behavioral change. You have to learn a new git system, and you have to learn an alternative to Gitflow/GitHub Flow. You can prevent this by enforcing everyone on the team to be strict about making small PRs, that are tied to small project management tickets.
Run git fetch
The functionality provided by GitHub for code review extends beyond the scope of what git does on your local machine.
Run git fetch to synchronize the latest changes in remote branches to your local branches. This way, when you run git checkout , you will have everything correctly set.
Connect PR Review with Slack
Another reason why developers spend 30% of their time in GitHub for code review is that they are so focused on the task they are working on, that they forget to review the code their peers created PRs for.
Luckily, they have a bot specifically designed to improve the GitHub for code review experience.
We’ve seen other practices such as manually creating a channel per Pull Request (and then deleting such channel once the PR is closed) being implemented. It might be a bit of an overkill and hard to thoroughly stick to every single time, but it also produces great results.
Automate code quality analysis
To improve your team’s experience using GitHub for code review, you should automate code quality analysis.
‍
Static code quality analysis tools such as SonarCloud, Code Climate, and DeepSource are great for this. They help you make sure that the code in your PR isn’t introducing technical debt or potential security vulnerabilities.
However, as important as it is in the GitHub for code review process, using static code quality analysis tools isn’t enough to make sure that Pull Requests will satisfy business requirements.
Write awesome pull request descriptions
Ensuring PRs are created with the correct branching model and size is basic. Updating local branches with remote changes is something that is forgotten a little bit more often but still paramount for properly using GitHub for code review. Keeping PRs visible to everyone and automating the more mechanical stuff such as checking for potential security vulnerabilities is going the extra mile, and it helps a lot.
You are sub-utilizing GitHub for code review if you are not writing awesome pull request descriptions. Beyond using a great PR template (which is outside the scope of this blog post), the content of the description section of your PR template should include:
What is the business objective trying to be achieved with this pull request?
Approaches tried, why is this the correct technical approach? Linking to related PRs is useful for this
If your team is using an agile methodology (like most other teams in the world today), link to the project management system ticket related to the task this PR is addressing.
Link to relevant documentation
Has there been any relevant conversation about this PR or the business logic it’s changing? A Slack message thread or a Zoom transcript perhaps?
‍
Our GitHub Application helps you automate the process of writing awesome pull request descriptions according to this criteria.
Top comments (0)