Introducing Turn-based Code Reviews in Space
Today, we want to introduce you to the concept of turn-based code reviews in Space! The idea behind turn-based code reviews is to make the process of reviewing code as clear as possible for the author of the code, and the reviewers.
When the Space team was looking at the typical code review process, we found two issues that could be improved:
- Who should take action? It’s not always clear whether the ball is in the court of the author or that of one of the reviewers.
- It is not uncommon for a reviewer to write: “Could you please explain the meaning of this part?”, and then delete their comment once they’ve found the answer to their question further in the code. Does it make sense to send comments immediately during a review, bothering the author and reviewers with what could be temporary remarks? Can comments be buffered as drafts, until we’re done with a review pass?
Inspired by the turn-based games we love – in which the procedure is governed by the rules of the game, and is usually clear to even the youngest of players – we’ve decided to introduce a turn-based code review process in Space. We’ve added status indicators for each of the participants, to reflect whose turn it is at any moment. Code review comments are also added as drafts, and sent in one go when someone’s turn in the review ends.
Turn-based review example for merge requests
You’re welcome to watch the screencast or read a step-by-step example with illustrations.
Step-by-step example with illustrations
1. Maarten has finished working on a task and wants his code to be reviewed before merging it to master. He creates a merge request and adds Heather as a reviewer.
From this moment on, the process looks different for each participant. Maarten’s status is set to Waiting, which reflects that he’s waiting for feedback from Heather.
From Heather’s side, she sees that a new item marked with the Needs review status has been added to the Needs my review list. The author is waiting, and it’s now the reviewer’s turn.
- Heather opens the review and clearly sees that her current status is Reviewing.
- Heather opens the files, reads the code, and sees there is room for improvement. She wants to add several comments.
4. Heather writes a comment, and saves it as a draft by pressing the Enter key (⏎) instead of sending it right away (similar to GitHub). She also has the option to send the comment immediately using the Post now (⌘⇧P) option. Heather writes two more comments and is ready to complete her turn.
If everything is perfectly clear, Heather can simply select Accept changes.
If any parts of the code are still unclear, or if any unresolved issues remain, Heather can pass the buck back to Maarten by using the Wait for response option. We’ve tried to give this option a totally neutral label, taking into account our previous experience with the Raise concern label, which seemed to assume that the review required changes even when this was not always true.
5. Heather is not ready to Accept changes, and chooses the Wait for response option. All the comments are now submitted, and the turn comes back to Maarten.
6. Maarten opens the code review and replies to the comments, either using drafts or sending the comments right away.
7. After Maarten has replied to all the comments and has made the commit with fixes, he is ready to complete his turn using the Update review button.
At this point, all the comments are sent to Heather and she’s notified that the merge request needs to be reviewed. Now it’s Heather’s turn.
8. This time everything looks good, and Heather clicks Accept changes.
Now the turn passes back to Maarten. Since there’s nothing left for him to do, Space suggests that he uses this turn to merge his changes.
9. Maarten merges his changes using Rebase and squash. This option combines all the commits, including the addition commit with code review changes, into a single commit in the master branch.
Now the code review process is complete.
What about regular code reviews?
The process for regular code reviews is similar. The only difference is that the code review closes automatically when all the reviewers have accepted the changes and there are no unresolved discussions.
How to get started?
Turn-based code review is already available for all Space cloud organizations. Newly created code reviews and merge requests automatically follow the turn-based process. Any reviews that had been created before this change went into effect will not have most of the newly introduced status indicators (except for Accepted and Raised concern). However, you can still create drafts for comments.
We really hope that you enjoy the new turn-based code review experience. It might even remind you of playing your favorite turn-based game!
Give code review a try and share your experience with us! By the way, we’ve introduced a new option to send your feedback directly from Space:
Join the free Space EAP (Early Access Program) and become one of the early adopters today. We’re looking for your input to make Space an incredible place for every kind of creative team in the world!
Subscribe to Space Blog updates
