Reviews

​

What are Reviews?

Code reviews in Diversion let you request feedback on your changes before merging them into your main branch. Team members can review your code, leave comments, approve changes, or request modifications.

​

How Reviews Work

A review compares two refs (branches or commits) in your repository:

• Base ref: The target where changes will be merged (usually main)
• Compare ref: The branch or commit containing your changes

When you create a review, Diversion calculates the differences between these two refs and presents them to your team for feedback.

​

Creating a Review

There are two ways to create a review in Diversion:

​

Method 1: Create Review from Branch (Most Common)

Use this when you want to compare two branches and get feedback before merging. Step-by-Step Instructions:

1. Navigate to Reviews section
   • Open your repository in Diversion web app
   • Click on the “Reviews” icon in the left navigation rail, or press Ctrl+K (Cmd+K on Mac) and choose Reviews
   
2. Click “Create new review” button
3. Select branches to compare
   • Base branch: Select the branch you want to merge INTO (usually main)
     • Click the dropdown under “Base branch”
     • Choose your target branch (e.g., master, main, develop)
   • Compare branch: Select the branch WITH your changes
     • Click the dropdown under “Compare branch”, or start typing to search for a branch
     • Choose your feature branch (e.g., feature/user-dashboard)
4. Fill in review details
   • Title (required): Short description of your changes
     • Example: “Add user authentication system”
   • Description (optional): Detailed explanation
     • Explain WHY you made these changes
     • Mention any important context
5. Add reviewers (optional)
   • Click the “Reviewers” dropdown
   • Select one or more teammates who should review your changes
   • You can skip this and add reviewers later
6. Click “Create review”
   • The review will be created immediately
   • Assigned reviewers will receive email notifications
   • You’ll be taken to the review page

​

Method 2: Create Review from Merge Dialog

Use this when you’re ready to merge but need approval first Step-by-Step Instructions:

1. Navigate to the branch you want to merge
   • Go to the “Branches” section in Diversion web app
   • Find your feature branch (the one WITH your changes) in the Branches list
   • Click on that branch and choose the merge direction
   • Notes: You cannot merge the branch you’re currently on. You must click on a different branch to see merge options
   
2. Choose “Create review request”
   • A dialog appears asking how you want to proceed
   • You’ll see several options, including:
     • “Create review request”: Request review before merging
     • “Preview merge”: See merge diff without creating review
   • (The dialog also offers “Merge now” and “Cancel”.)
   • Click “Create review request”
   
   • If a review already exists for these branches, click “Go to review requests”
   
3. Fill in review details
   • If a review already exists for these branches, it will take you there
   • Otherwise, you’ll see the review creation form
   • The base and compare branches are already filled in
   • Add title, description, and reviewers
   • Click “Create review”

​

What You Need for All Methods

Every review requires:

• Base branch: Where you want to merge your changes (e.g., master)
• Compare branch: The branch with your changes
• Title: A clear, concise description (required)
• Description: More detailed explanation (optional but recommended)
• Reviewers: Teammates who should review (optional, can add later)

​

Reviewing Someone’s Changes

​

When You’re Asked to Review

You’ll get an email notification when someone requests your review. Step-by-Step Instructions:

1. Open the review
   • Click the link in your email notification, OR
   • Go to Diversion web app → “Reviews” section
   
   • Find the review in the list (you’ll see your name as a reviewer)
   • Use the Filter by row to narrow the list. The list shows open reviews by default.
     • Status: Open, Closed, or both
     • Author and Reviewer: choose Me, people, or groups. A group matches any of its members
     • Branch: matches the base or the compare branch of a review
   
   • Filters work together and with the search box. For example, Author: Art shows only reviews opened by members of the Art group
   
   • Organization owners and admins see all groups. Other members see the groups they belong to
   • Click Clear filters to show all reviews
   • Click on the review to open
2. Look at the review details
   • At the top, you’ll see:
     • Review title and description
     • Who created the review
     • Which branches/commits are being compared
     • Current status and other reviewers
3. Review the changes
   • You’ll see two tabs:
     • “Conversation”: Shows all comments and discussion
     • “Files Changed”: Shows the code diff
   • Click “Files Changed” to see what code changed
   
4. Leave comments (explained below)
   • Add general comments about the overall changes
   • Add inline comments on specific lines of code
   
5. Make your decision
   • Go to the “Files Changed” tab
   • Click “Review changes”
   
   • Choose one of these options:
     • “Approve”: Changes look good, ready to merge
     • “Request Changes”: Something needs to be fixed
     
   • If you created the review, these two options are disabled. You can still add a comment.
   • Add an optional comment to explain your decision
   • Click the “Submit review” to submit your decision
6. Done!
   • The review author receives notification of your decision
   • Your review status will be updated and appear both in the conversation and on your avatar under the “Reviewers” section

​

Adding Comments

​

General Comments

Use general comments for big-picture feedback about the whole review. How to add a general comment:

1. Open the review page
2. Go to the “Conversation” tab
3. Scroll to the comment box at the bottom
4. Type your comment
5. Click “Comment” button

How to reply to a comment:

1. Find the comment you want to reply to in the “Conversation” tab
2. Type your response
3. Click “Reply” to post your reply

Examples of general comments:

• “The overall approach looks great!”
• “Have you considered how this handles edge cases?”
• “This needs unit tests before we can merge”
• “Great work on the error handling!”

​

Inline Comments

Use inline comments to point out specific issues in particular lines of code. How to add an inline comment:

1. Open the review page
2. Go to the “Files Changed” tab
3. Find the file you want to comment on
4. Click the line number in the diff view
5. A comment box appears on the right side of the screen
6. Type your comment about that specific line
7. Click “Comment” button

How to add a file-level comment:

1. Open the review page
2. Go to the “Files Changed” tab
3. Find the file you want to comment on
4. Click the ”+” button above the changed version of the file
5. A comment box appears on the right side of the screen
6. Type your comment about the entire file
7. Click “Comment” button

Examples of inline comments:

• “This function should handle the case where user is null”
• “Consider using a constant here instead of magic number”
• “Great improvement over the previous version!”
• “This could cause a race condition if called concurrently”

​

Resolving and Folding Threads

When a discussion is settled, resolve its thread so the review shows what is still open. How to resolve a thread:

1. Find the thread in the “Conversation” tab, or in the comments on the right of the “Files Changed” tab
2. Click “Resolve thread” under the thread
3. The thread folds into one line that shows who resolved it and when

To open a resolved thread again, click its folded line and then click “Unresolve thread”. A new reply does not open a resolved thread. Who can resolve: anyone with write access to the repository. Users with read-only access can comment but cannot resolve. Unresolved count: the “Conversation” tab shows how many threads are still open. In the “Files Changed” tab, the comments on the right show the count for the selected file. Folding without resolving: click “Fold” at the top of any thread to hide it, and click the folded line to show it again. Folding changes only your view.

​

Viewing Review Status

Your status as a reviewer:

• REQUESTED: You haven’t responded yet - review is waiting for you
• APPROVED: You approved the changes
• CHANGES REQUESTED: You requested modifications

The review’s overall status:

• OPEN (blue): Review is active, may still need approvals
• MERGED (purple): Changes were approved and merged
• CLOSED (gray): Review was closed without merging

​

Editing Review Details

After creating a review, you can edit the title and description by clicking the pencil icon next to them, or edit reviewers by clicking the settings icon next to the reviewers section.

​

Working with Review Feedback

​

When Changes Are Requested

1. Read through all the comments carefully
2. Make the requested changes on your branch
3. Commit the fixes (they’ll automatically show up in the review)
4. Reply to comments to explain what you changed
5. Ask reviewers to take another look

​

Updating Your Branch

If you’re using a branch review, any new commits you push will automatically appear in the review. Reviewers will see:

• All your original changes
• Any new commits you added to address feedback
• The complete, updated diff

​

Check for Merge Conflicts

Before you merge, check if the review conflicts with the base branch. Open the “Conversation” tab:

• If the review has conflicts, a banner says “This branch has conflicts that must be resolved” and lists the conflicting files. Click a file name to open it on the “Files changed” tab.
• “Merge review” stays disabled until the conflicts are resolved.
• Click “Resolve conflicts” to merge the latest changes from the base branch into your branch and open the conflict screen. When you finish, Diversion takes you back to the review.

If the base branch has new changes that do not conflict, the banner says “This branch is out-of-date with the base branch” instead. Click “Update branch” to bring those changes into your branch. On the “Files changed” tab, a conflicting file has a warning icon (an exclamation mark) next to its name: Select the file to see a message that it conflicts with the base branch. The diff shows the changes from your branch.

​

When You Get Approvals

Once all reviewers have approved (or enough approvals based on your team’s policy):

1. Do a final check that everything looks good
2. Click the “Merge review” button on the review page to merge the changes. If you left the conflict screen before you finished, the review shows a “Resolve conflicts” button that takes you back to it.
3. The review status will automatically change to MERGED

​

Notifications

You’ll get email notifications for:

• When someone requests your review
• When someone comments on your review
• When reviewers approve or request changes
• When a review is merged or closed

All notifications include a link to view the review in Diversion.