Review Screen
This page contains information about the Review screen where code reviews are fulfilledonce a reviewer gains access to a review.
Last updated
This page contains information about the Review screen where code reviews are fulfilledonce a reviewer gains access to a review.
Last updated
From the review screen, the reviewer can toggle between a view of the code diff and a timeline recording of commits, summary comments, and inline comments.
For every code review, the PullRequest team encourages taking a look at the Timeline view before getting started to get familiar with any information shared in conversations prior to the reviewer's involvement.
From the code view, there is a file tree available from the collapsable sidebar which lists all of the files involved in the code review job in a directory relation view. Jump to specific files in the diff view by clicking on the files.
From the code view Settings menu, the following review setting options are available:
Toggle between light, dark, and auto OS mode
Toggle between viewing the diff in a split, unified, or hybrid view.
Hide whitespace changes in diffs.
Render all files at once or render files individually.
Toggle on/off inline highlighting for changes made since a diff was last reviewed.
Controls for displaying PullRequest's Automation Results.
Within the code view, reviewers can use the Search bar to search a code review for things like method names, variables, strings, and more.
Search results are presented and separated in the following two ways:
Files touched in this review - These results are from files that were modified and relevant to the merge request under review.
Other files in the repository - These results are from other files in the repository that weren't modified as part of the proposed change.
NOTE: PullRequest customers have the option to opt out of exposing other files from the repository with this search feature. If the organization that owns the code being reviewed has opted out, there will be a message shown indicating this.
Learn more about PullRequest's search tool here.
The commit selector allows reviewers to select a single commit or a range of commits to view rather than all of the changes at once. Click the selector to open it.
The dropdown includes a list of commit names, revisions, and tags representing various information about each commit. The commits are generally ordered from oldest to newest changes. The last commit in the list will always be the latest change.
The following information is displayed in the drop down for each commit:
The commit description
Colored dots representing each branch
The merge tag for applicable commits
A shortened commit hash
If there are a group of commits listed with one color followed by a merge tag, the color change may represent a merge into a different branch.
Single commits can be selected by clicking on them. A range of commits can also be selected by holding the Shift key while clicking.
Due to the nature of Git, selecting a merge commit is not possible. When selecting a range of commits, commits from different branches (a differently colored dot) or merge commits cannot be included.
Because of the underlying comment posting mechanism and because we're supporting multiple back end providers, it will sometimes not be allowed to leave comments if all changes are not being viewed. To return, click "Show all changes":
Inline comments can be added to lines of addition and deletions, but also to lines without a detectable change within the default context, which spans 3 lines above and below the block of changes.
We encourage reviewers to expand files involved with the set of changes to better understand or re-acclimate with the environment. If there are any issues worth mentioning on a line that cannot be commented on, feel free to add a note in the summary comment with line number reference when submitting.
The PullRequest reviewer platform will save all of the comments being made in real-time as they are being typed, even if the browser is completely closed and re-opened. Unless deleted, comments will be associated with a reviewer profile both before and after the review is submitted.
Inline and summary comment fields support markdown syntax formatting. PullRequest encourages reviewers to apply markdown syntax formatting to any references of code to optimize for readability and help developers apply suggested changes. The Preview link will display the text in markdown to quickly reveal any issues with formatting.
See the Markdown Syntax Guide for more.
Each inline comment should be categorized by type of feedback or information being presented. As reviewers start to input information, comment categories options become available.
The following table explains the intent for each category available from the comment category selector. Reviewers should do their best to select the category that makes the most sense based on their own judgment.
Often feedback provided in an inline comment will overlap with 2 (or more) of these categories. When in doubt, use best judgment as to which would be most appropriate.
Along with the manual selection, a comment category prediction feature is available to use. After a comment has been made, click the lightning bolt to activate the feature for the comment. Existing commentary is analyzed and the prediction tool will take context provided and come up with a most likely category, severity, and confidence level. This feature uses from all of the stored inline comments to best predict how the comment should be categorized. Adjust the categories to be accurate, as needed. Any corrections will help to refine the prediction model over time and improve workflow on the platform.
Often times a code review job will include existing comments from other PullRequest reviewers and the client's internal team members. Reviewers can reply to these discussions and they will appear threaded in the client's version control provider.
After completing a review, submit the review by clicking the Review button in the top-right corner of the screen. This will include a circle icon with a counter indicating the number of saved comments that will be submitted.
A review summary comment is required for the first review submission for a code review job and is optional thereafter (for submitting follow-up inline comments or responding to replies). It's a good idea to provide a summary of what has been done through this iteration of the review. If there are any other broad considerations that the code authors should know about the review, this is a good place to leave them.
Like inline comments, summary comments auto-save as they are being created. They'll be accessible again even if the browser is closed and re-opened.
In some cases, reviewers are not be able to post feedback to the client at the time of review completion. This generally will occur either when there is a custom review project where all review content needs to be submitted at one time or in cases where a PullRequest account executive needs to screen content before it's submitted.
If a review is locked, a confirmation message will appear at the time of submission.
Some code review jobs involve a very big set of changes which the reviewer may not be able to complete in a single sitting. It is also possible that a job that has been claimed has ongoing commits that outdate some of the comments being made during an active review.
In these cases where follow up is needed, the best practice is to submit the feedback gathered so far with a line somewhere in the summary comment indicating that a full review was not yet completed. If the author is still committing to the PR, make sure to delete any comments that have become outdated and post in the summary comment a request for response once they are finished with commits.
Fatigue effects are real! For very large code review jobs, PullRequest encourages reviewers to submit feedback in multiple passes.
Example:
Category
Description
Best Practices
Feedback regarding best practices for things like the programming language or framework used, general architecture, etc.
Bug
Calling out a clear or potential bug.
Dead Code
Calling attention to what appears to be dead code.
Error Handling
There is a potential issue with error handling or error handling is absent when it should otherwise be expected.
Security
A potential security or privacy concern.
Spelling/Typo
A clear or potential typo in code or in things a string that will be visible to users.
Code Reuse
Feedback that will help reduce repeated code in the codebase.
Improve Readability
Feedback for ways to improve the code's readability and reduce cognitive load.
Naming
A suggestion for a potentially better name to use for an identifier.
Reduce Future Bugs
A suggestion that will likely reduce the introduction of a bug later.
Simplify Code
Feedback for ways to simplify the codebase.
Style Consistency
Calling attention to inconsistencies in how the code is written and/or organized.
Giving Information
Presenting useful information to the code author.
Question
A question for the code author that isn't related to any of the categories described above.
Compliment
Complimenting the code author on something that was well done.
These are important, too! 🎉
