Upsource Web 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.

In the end, it’s up to your team to choose the optimal workflow for the code review process, and Upsource imposes few restrictions in this regard. Except that it only allows you to review after committing, not the other way around.

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:

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.

Click your revision’s title to open it up. You’ll be redirected to a Revision view.

To initiate a review, click Create review in the upper right corner:

That’s it! A new review is created 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, 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 below the corresponding heading. Then select a name from the pop-up list:

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

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 code selection comment, 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):

To leave a line comment, go to the review home view, expand the file and select the line you want to comment on by clicking the edit icon to the left:

Add line comment

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

Add line comment

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 displays the changes in each file included in the revision or revisions that are subject of the review. If someone has already commented on code fragments or lines, these comments will be embedded in code and highlighted with yellow:

General review comments are displayed at the bottom of the page in the review timeline:

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 mark the review as complete:

Complete review

In case you found some issues:

  1. Comment on the issues requesting further improvements.

  2. Mark the review as complete.

  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.

If it’s necessary to only see latest changes (as opposed to all revisions in the review combined), you can open the latest of the review’s revisions and inspect improvements in a Side-by-side diff, resolving outdated comments along the way.

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 Remove icon next to the revision name:

Attach from review

Closing review

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

Attach from review