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?
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.
Code reviews can also help:
- new teammates learn about different parts of the project faster
- promote collective code ownership
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.
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.
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:
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, 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 .
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 and click the plus sign next to the corresponding heading. Then select a name from the pop-up list:
To assign the two most suitable reviewers (based on previous assignments) without opening the reviewer selection pop-up, click Assign reviewers automatically.
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:
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
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:
Enter your message in the text box and click Add comment:
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:
All 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 press Accept. After that the review is considered completed.
In case you found some issues:
Comment on the issues requesting further improvements.
Press Reject - the author will see that you rejected 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:
To see all the reviews you are involved with, go to the Reviews tab in the project home view.
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:
As soon as all reviewers have completed the review and no further changes are expected, the review author should close it: