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 your 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.

Post-commit review

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.

Move your cursor to the revision entry — a Create review link will appear:

To initiate a review, click Create review. That's it! A new review is created, opened, and its ID is displayed at the top left:

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.

Going back to the revisions list, you can notice that your revision is now flagged with a clickable Review icon .

Inviting participants

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 either accept your changes or raise concern about them.
• 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 might suggest you the most suitable reviewers (based on previous assignments) whom you can assign without opening the reviewer selection pop-up.

You can also mention other users while writing a comment, and this will automatically add them to watchers of your review: just type @ in the text field and the same list will appear.

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 in the project home view.

To remove a participant, click their userpic in the Reviewers area and confirm the deletion:

Viewing changes

The files with changes are listed under the Overview tab. Click on the file name to display the inline diff:

From here you can go to a side-by-side diff or view the entire file by pushing the corresponding button:

To return to the timeline view, press Esc.

Leaving comments

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.

To leave a review comment, type your message in the text field at the bottom:.

To leave a line comment, display the inline diff of the file you want by clicking on the file name, then select the line you want to comment on by clicking the edit icon to the left:

Enter your message in the text box and click Add comment:

To leave a code selection comment, from the inline diff view of the desired file go to Side-by-side diff or View file and select the fragment you want to discuss.

Choose Comment on selection from the pop-up menu. Type in your message and click Add comment (or press Ctrl+Enter ):

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.

If you approve the changes, you simply press Accept. After that the review is considered completed.

In case you found some issues:

Revision selector

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:

Reset to default brings the selection back to the state it was when you opened the review.

To see all the reviews you are involved with, go to the Reviews tab in the project home view.

Adding revisions

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.

Closing review

As soon as all reviewers have completed the review and no further changes are expected, the review author should close it:

Removing review

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.

Click the Edit icon next to the review title:

Then push the Remove review button.