Upsource 2.5 Help

Code review with Upsource

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

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 list of indexed projects, where each project corresponds to a specific VCS repository:

Project list

Clicking a project name brings you to the project's home view that lists (and visualizes) revisions in chronological order:

assets/codereview/CR_revList_large.png

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:

Project list

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:

assets/codereview/CR_revCreate_large.png

The default review title is the same as your revision which becomes a part of this review. To change the review title, click the Edit icon Edit icon next to it.

The default review title is the same as your revision which becomes a part of this review. To change the review title, click the Edit icon !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 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 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:

assets/codereview/CR_pickReviewer_large.png

Upsource suggests you the most suitable reviewers (based on previous assignments) which 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 alongside the project root view and the list of projects.

To remove a participant, click its user pic in the Reviewers area and confirm the deletion:

Project list

Viewing changes

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

CR_click_file_for_diff.png

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

assets/codereview/CR_review_inline_diff_large.png

To return to the timeline view, click Timeline or press Esc:

CR_click_timeline.png

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

assets/codereview/CR_genComment_large.png

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:

assets/codereview/CR_addLineComment_large.png

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

assets/codereview/CR_lineComment2_large.png

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 ):

assets/codereview/CR_comMenu_large.png

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.

assets/codereview/CR_postedGenComm_large.png

You can customise it to show only discussions or unresolved discussions:

timeline_view_options

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:

assets/codereview/CR_inlineComment_large.png

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.

Complete review

In case you found some issues:

  1. Comment on the issues requesting further improvements.
  2. Press Reject - the author will see that you rejected his changes and completed the review.
  3. Wait for the author to commit the fixes.
  4. 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:

Complete 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:

assets/codereview/CR_attachToReview_large.png

or from the review:

CR_addRevision.png

To detach a revision from a review, in the review home view, click the Detach icon next to the revision name:

assets/codereview/CR_detach_large.png

Opening revisions in IDE

When you click this link, the revisions included in the review will be displayed in the Version control 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.

CR_open_in_IDE

Closing review

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

CR_closeRev.png

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. Just push the Remove review button.

CR_remove_review.png
Last modified: 14 September 2016