Musings of a trainer of geeks.

Streamlining pull request reviews with suggestions

2022-08-29 DevOps geektrainer

We’ve all been there. We’re reviewing someone’s code in a pull request (PR) and we spot a small mistake. A typo. The wrong option was set. A boolean flag was reversed. Something simple. What’s the best way to suggest a fix?

One way is to create new branch and PR into the one you’re reviewing. Seems like a bit too much work, and maybe a little too formal.

For a repository where you have permissions, you could simply push the updates. But this could mean missing an opportunity to help a junior developer learn something new.

You could take the lazy route and just add a comment to the PR. This just adds work to the developer who submitted the PR as they need to add the change you suggested.

The best option? To make a suggestion to the file!

Add a suggestion

When you are reviewing a PR, the Files changed tab lists all the files changed[1] in the PR. From there you can select the + next to any line and add a comment for that specific line of code. After opening the comment dialog you might notice a +- icon towards the middle. That’s the Add a suggestion option!

Screenshot of the files changed comment dialog with Add a suggestion circled

Hitting that button will put a new code section into the comment containing the line you chose for the comment. The modifications you make now become the suggestion for the PR. In the example I’m using, EmailField is a better option for the email field in the sample Django project.2 I’ve updated the code with EmailField and added a comment below it.

Screenshot of the files changed comment dialog with the updated code

After making the suggestion and comment, you can select Start review and continue to review the code (and make more suggestions) as normal. When you’re ready to submit your review, you select Finish review, add any overall comments, choose the Request changes option, and finally Submit review.

The comment(s) become part of the PR log just like normal comments. Only this time they include a neat little button which says Commit suggestion. The original author can how accept the suggestion by selecting that button and Commit changes. Reviewing from the Files changed tab includes the option to Add suggestion to batch and Commit suggestions to commit all selected items in one press of a button!

Screenshot of commit suggestion dialog

Help your teammates

Code suggestions are a wonderful way to streamline the review process. With a couple of buttons you are able to both suggest updates and comment, and make it easier for the original developer to incorporate the requested fixes. It’s perfect for typos and other small updates.

1 It’s a clever name 2 I’m a huge fan of Django, which is a great Python web framework.