Code review demo
Here we will practice the code review process. We will learn:
how to ask for changes in a pull request;
how to suggest a change in a pull request;
how to modify a pull request.
This will enable research groups to work more collaboratively, which should help to
improve the code quality
learn from each other.
Note that pair programming
is usually seen as possible alternative
to code review.
Compared to the practice of code review,
it has its own pros and cons.
Exercise
Exercise preparation
We can continue in the same exercise repository which we have used in the previous episode.
Exercise: Practicing code review (25 min)
Technical requirements:
If you create the commits locally: Being able to authenticate to your preferred forge
What should be familiar:
Creating a branch (lesson from CodeRefinery)
Committing a change on the new branch (lesson from CodeRefinery)
Opening and merging pull requests (lesson from CodeRefinery)
What will be new in this exercise:
As a reviewer, we will learn how to ask for changes in a pull request.
As a reviewer, we will learn how to suggest a change in a pull request.
As a submitter, we will learn how to modify a pull request without closing the incomplete one and opening a new one.
Exercise tasks:
Create a new branch and one or few commits: in these improve something but also deliberately introduce a typo and also a larger mistake which we will want to fix during the code review.
Open a pull request towards the main branch.
As a reviewer to somebody else’s pull request, ask for an improvement and also directly suggest a change for the small typo. (Hint: suggestions are possible through the GitHub web interface, view of a pull request, “Files changed” view, after selecting some lines. Look for the “±” button.)
As the submitter, learn how to accept the suggested change. (Hint: GitHub web interface, “Files Changed” view.)
As the submitter, improve the pull request without having to close and open a new one: by adding a new commit to the same branch. (Hint: push to the branch again.)
Once the changes are addressed, merge the pull request.
Help and discussion
From here on out, we don’t give detailed steps to the solution. You need to combine what you know, and the extra info below, in order to solve the above.
Asking for changes in a pull request: 2 ways
Either in the comment field of the pull request:
Or by using the “Review changes”:
And always please be kind and constructive in your comments. Remember that the goal is not gate-keeping but collaborative learning.
Suggest a change in a pull request as a reviewer
If you see a very small problem that is easy to fix, add a comment by clicking on the sign next to the line number in the tab that shows the changes:
Here you can comment on specific lines or even line ranges.
Click on the “Add suggestion/Insert suggestion” symbol. Now you can fix the tiny problem (in this case a typo) and then click on the “Add single comment” button:
The result is this and the submitter can accept the change with a single click:
After accepting with “Commit suggestion”, the improvement gets added to the pull request.
How to modify a pull request to address the review comments
If the reviewer asks for changes, it is not necessary to close the pull request and later open a new one. It can even be counter-productive to do so: This can fragment the discussion and the history of the pull request and can make it harder to understand the context of the changes.
A much better mechanism to recognize that pull requests are not implemented from a specific commit to a specific branch, but always from a branch to a branch.
This means that you can make amendments to the pull request by adding new commits to the same source branch. This way the pull request will be updated automatically and the reviewer can see the new changes and comment on them.
The fact that pull requests are from branch to branch also strongly suggests that it is a good practice to create a new branch for each pull request. Otherwise you could accidentally modify an open pull request by adding new commits to the source branch.
Summary
Our process isn’t just about code now. It’s about discussion and working together to make the whole process better.
GitHub discussions and reviewing is quite powerful and can make small changes easy.