Code review with Upsource
On this page:
- Why review code?
- Post-commit review
- Starting a code review
- Inviting participants
- Viewing changes
- Leaving comments
- Participating in review
- Revision selector
- Adding revisions
- Opening revisions in IDE
- Closing review
- Removing review
Upsource makes it easy for you and your team to review code, discuss changes, and keep track of accumulated knowledge.
A code review in Upsource can be associated with one or more revisions, or an entire branch. Once initiated, a code review becomes a separate entity with a unique ID, allowing you and your team members to exchange comments over specific lines of code or discuss changes in general.
However, why would you review code at all?
Why review code?
There can be many reasons for you to start a code review, and here are just a few of them:
- You have committed a change and now you want your fellow teammate to examine it and help you make sure that the new code is clear, readable and doesn't contain any serious flaws.
- You have stumbled upon a potential problem in your teammate's change and you want to draw their attention to it.
- You want to keep some of you teammates updated of your project status whenever an important change is made.
- New teammates learn about different parts of the project faster
- Promote collective code ownership
Upsource supports post-commit reviews, which means you should commit a change to your VCS repository before a review can be initiated.
If your organization requires that code is reviewed before it gets merged into the master branch (trunk), you can commit to your feature branch and request review of this commit.
As soon as code review of this commit is successfully passed, you can then merge your changes to the master branch.
Starting a code review
Let's consider a scenario whereby you have committed a change, and now you want to ask your teammate to review it.
When you log into Upsource, the first thing you see is the lists of indexed projects, where each project corresponds to a specific VCS repository.
Clicking a project name brings you to the project's home view that lists (and visualizes) revisions in chronological order:
To find the revision you're interested in, just scroll down the list or use Search on top of it. In our case, your commit will likely be at the top of the revision list.
The default review title is the same as your revision which becomes a part of this review. To change the review title or to remove this review altogether (in case you've created it by mistake) click the Edit icon next to it.
You created a review and now you want to invite some of your teammates to take a look and discuss its subject. That's easy. Just add them to the reviewers or watchers list depending on the action you want them to take.
- Reviewers are expected to... well, review your changes. They can discuss specific lines, or add general comments; they are also expected to mark the review as complete as soon as they're OK with the changes.
- Watchers aren't expected to take part in the review process. If you feel that you've made an important change (such as an API change), you can add watchers to keep them up to date.
To add a reviewer or a watcher, open the review and under the Overview tab click the plus sign next to the corresponding heading. Then select a name from the searchable pop-up list:
Upsource suggests you the most suitable reviewers (based on previous assignments) whom you can assign without opening the reviewer selection pop-up.
You can add as many participants as you wish and whenever you wish: when starting a review, or at any time after that.
The people you add are notified via e-mail and also via their personal Upsource news feed, which is shown alongside the project root view and the list of projects.
From here you can go to a side-by-side diff or view the entire file by pushing the corresponding button:
Whether you act as an author, reviewer or watcher, you can post comments, addressing them to other participants whose attention you want to draw.
There are three types of comments:
- Review comment: this type of comment is not tied up to any particular file or part of code - its subject matter may be anything within the scope of the review.
- Code selection comment: this type of comment is intended to pinpoint a particular code fragment in one of the files being reviewed.
- Line comment: this type of comment is associated with a specific line of code.
You can attach images to comments by dragging and dropping or pasting them from the clipboard.
Participating in review
When someone invites you to take part in a review, you'll receive a notice in your e-mail containing a direct link to that review.
Follow the link and proceed to the review page.
Its main pane shows the review timeline that lists all events and comments related to the review.
You can customise it to show only discussions or unresolved discussions:
In the left pane, you can see the list of files included in the revision or revisions that are subject of the review. Click on the file to display the inline diff and view the changes.
If someone has already commented on code fragments or lines, these comments will be embedded in code and highlighted with yellow:
As a reviewer you can reply to existing comments, post new review comments, or comment on code fragments and lines as well. You can also mark each discussion thread as resolved when it comes to a logical end.
In case you found some issues:
- Comment on the issues requesting further improvements.
- Press Raise concern - the author will see that you questioned his changes and completed the review.
- Wait for the author to commit the fixes.
- As soon as a new revision is added, the review is automatically un-completed. Examine the changes and complete the review again.
When new revisions are added to the review, you only see the diff of those revisions and can proceed with reviewing without having to inspect previously committed changes once again. If you want to show or hide any additional revisions within a review, use a revision selector that quickly toggles revisions on and off:
Let's say you initiated a review, asking for your teammate's opinion on the changes that you recently committed.
The reviewer spots issues in your changes and creates a comment describing them. Following the discussion, you work on these issues and commit a fix.
Now you can attach the new revision to the original review so your teammate can approve it. This way the whole discussion and revision history is contained within one review.
You can attach a new revision to an existing review either from that revision:
or from the review:
To detach a revision from a review, in the review home view, click the icon next to the revision name:
Opening revisions in IDE
When you click this link, the review and the revisions it includes will be displayed in a separate tab of the Review tool window of your currently opened IDEA-based IDE. For this option to work, the IDE should have the Upsource plug-in installed and configured and the project should be open in the IDE.
As soon as all reviewers have completed the review and no further changes are expected, the review author should close it:
Whether you've created a review by mistake, or want to clean up and get rid of outdated reviews, you can always delete a review no matter what its current status is.