A 4-Step Structure for Improving Your Pull Request Review Process for Better Code Delivery

Break through the friction by providing enough context for the reviewers to get up to speed. In other words: Give them context.

To achieve this, a strong pull request should have a clear structure including these sections:

An overview of what problem this change solves

The context that is important for understanding the blast radius of this change

How to evaluate the change and replicate in environments

Extra information

1. What’s the problem?

"It’s very easy to glaze over a diff and say 'okay, this looks good. Approved' and move on with your day." - Source

2. Why is it important to them?

"A PR is a messy page of stuff. It means something to you, it means a little less to your team, and it means even less to everyone else." - Source

3. Quality Assurance

"Make it easy for people to interact with the change in testing environments such as their local system or a shared development environment." - Source

4. Extras

"Screenshots, meeting notes, workflow recordings, concept documentation, async discussions, sample datasets for testing, known gotchas, etc." - Source

To wrap it up, think about your PR from the opposite viewpoint. If you were coming to it without understanding the context nor previous design preparation, what questions would you ask? Be prepared for those by providing answers and resources from the beginning.