| :linkattrs: | |
| = Review UI Overview | |
| Reviewing changes is an important task and the Gerrit Web UI provides | |
| many functionalities to make the review process comfortable and | |
| efficient. | |
| [[change-screen]] | |
| == Change Screen | |
| The change screen is the main view for a change. It shows the details of a | |
| single change and allows various actions on it. | |
| image::images/user-review-ui-change-screen.png[width=800, link="images/user-review-ui-change-screen.png"] | |
| Here are the main areas of the screen | |
| image::images/user-review-ui-change-screen-annotated.png[width=800, link="images/user-review-ui-change-screen-annotated.png"] | |
| === Top info | |
| Top left, you find the status of the change, and a permalink. | |
| image::images/user-review-ui-change-screen-topleft.png[width=600, link="images/user-review-ui-change-screen-topleft.png"] | |
| [[change-status]] | |
| The change status shows the state of the change: | |
| - `Active`: | |
| + | |
| The change is under active review. | |
| - `Merge Conflict`: | |
| + | |
| The change can't be merged into the destination branch due to conflicts. | |
| - `Ready to Submit`: | |
| + | |
| The change has all necessary approvals and fulfils all other submit | |
| requirements. It can be submitted. | |
| - `Merged`: | |
| + | |
| The change was successfully merged into the destination branch. | |
| - `Abandoned`: | |
| + | |
| The change was abandoned. It is not intended to be updated, reviewed or | |
| submitted anymore. | |
| - `Private`: | |
| + | |
| The change is marked as link:intro-user.html#private-changes[Private]. And has | |
| reduced visibility. | |
| - `Revert Created|Revert Submitted`: | |
| + | |
| The change has a corresponding revert change. Revert changes can be created | |
| through UI (see <<actions, Actions section>>). | |
| - `WIP`: | |
| + | |
| The change was marked as "Work in Progress". For example to indicate to | |
| reviewers that they shouldn't review the change yet. | |
| [[star]] | |
| === Star Change | |
| Clicking the star icon bookmarks the change: it turns on | |
| email notifications for this change, and the change is added to the | |
| list under `Your` > `Starred Changes`. They can be queried by the | |
| link:user-search.html#is[is:starred] search operator. | |
| [[quick-links]] | |
| === Links Menu | |
| Links menu contains various change related strings for quick copying. Such as: | |
| Change Number, URL, Title+Url, etc. The lines in this menu can also be accessed | |
| via shortcuts for convenience. | |
| image::images/user-review-ui-copy-links.png[width=600, link="images/user-review-ui-copy-links.png"] | |
| [[change-info]] | |
| === Change metadata | |
| The change metadata block contains detailed information about the change. | |
| image::images/user-review-ui-change-metadata.png[width=600, link="images/user-review-ui-change-metadata.png"] | |
| - [[owner]]Owner/Uploader/Author/Committer | |
| + | |
| Owner is the person who created the change | |
| + | |
| Uploader is the person who uploaded the latest patchset (the patchset that will | |
| be merged if the change is submitted) | |
| + | |
| Author/Committer are concepts from Git and are retrieved from the commit when | |
| it's sent for review. | |
| - [[reviewers]]Reviewers: | |
| + | |
| The reviewers of the change are displayed as chips. | |
| + | |
| For each reviewer there is a tooltip that shows on which labels the | |
| reviewer is allowed to vote. | |
| + | |
| New reviewers can be added through reply dialog that is opened by clicking on | |
| the pencil icon or on "Reply" button. Typing into the reviewer text field | |
| activates auto completion of user and group names. | |
| + | |
| - [[cc-list]]CC: | |
| + | |
| Accounts in CC receive notifications for the updates on the change, but don't | |
| need to vote/review. If the CC'ed user votes they are moved to reviewers. | |
| + | |
| - [[attention-set]]Attention set: | |
| + | |
| Users in attention set are marked by "chevron" symbol (see screenshot above). | |
| The mark indicates that there are actions their attention is required on the | |
| change: Something updated/changed since last review, their vote is required, | |
| etc. | |
| + | |
| Changes for which you are currently in attention set can be found using | |
| `attention:<User>` in search and show up in a separate category of personal | |
| dashboard. | |
| + | |
| Clicking on the mark removes the user from attention set. | |
| [[remove-reviewer]] | |
| Reviewers can be removed from the change by selecting the appropriate option on | |
| the chip's hovercard. Removing a reviewer also removes current votes of the | |
| reviewer. The removal of votes is recorded in the change log. | |
| Removing reviewers is protected by permissions: | |
| ** Users can always remove themselves. | |
| ** The change owner may remove any zero or positive score. | |
| ** Users with the link:access-control.html#category_remove_reviewer[ | |
| Remove Reviewer] access right, the branch owner, the project owner | |
| and Gerrit administrators may remove anyone. | |
| - [[repo-branch-topic]]Project (Repo) / Branch / Topic: | |
| + | |
| The name of the project for which the change was done is displayed as a | |
| link to the link:user-dashboards.html#project-default-dashboard[default | |
| dashboard] of the project. If no default dashboard is defined, the link | |
| opens a list of open changes on the project. | |
| + | |
| The name of the destination branch is displayed as a link to a list | |
| with all changes on this branch that have the same status as the | |
| currently viewed change. | |
| + | |
| If a topic was assigned to the change it is displayed below the branch. | |
| By clicking on the edit icon the topic can be set. This requires the | |
| link:access-control.html#category_edit_topic_name[Edit Topic Name] | |
| access right. To be able to set a topic on a closed change, the | |
| `Edit Topic Name` must be assigned with the `force` flag. | |
| - [[parent]]Parent: | |
| + | |
| Parent commit of the latest uploaded patchset. Or if the change has been merged | |
| the parent of the commit it was merged as into the destination branch. | |
| - [[merged-as]]Merged As: | |
| + | |
| The SHA of the commit corresponding to the merged change on the destination | |
| branch. | |
| - [[revert-created-as]]Revert (Created|Submitted) As | |
| + | |
| Points to the revert change, if one was created. | |
| - [[cherry-pick-of]]Cherry-pick of | |
| + | |
| If the change was created as cherry-pick of some other change to a different | |
| branch, points to the original change. | |
| - [[submit-strategy]]Submit Strategy: | |
| + | |
| The link:project-setup.html#submit_type[submit strategy] that will be | |
| used to submit the change. The submit strategy is only displayed for | |
| open changes. | |
| - [[hastags]]Hashtags: | |
| + | |
| Arbitrary string hashtags, that can be used to categorize changes and later use | |
| hashtags for search queries. | |
| [[submit-requirements]] | |
| === Submit Requirements | |
| image::images/user-review-ui-submit-requirements.png[width=600, link="images/user-review-ui-copy-links.png"] | |
| Submit Requirements describe various conditions that must be fulfilled before | |
| the change can be submitted. Hovering over the requirement will show the | |
| description of the requirement, as well as additional information, such as: | |
| corresponding expression that is being evaluated, who can vote on the related | |
| labels etc. | |
| Approving votes are colored green; negative votes are colored red. | |
| For more detail on Submit Requirements see | |
| link:config-submit-requirements.html[Submit Requirement Configuration] page. | |
| [[actions]] | |
| === Actions: | |
| Actions buttons are at the top right and in the overflow menu. | |
| Depending on the change state and the permissions of the user, different | |
| actions are available on the change: | |
| ** [[submit]]`Submit`: | |
| + | |
| Submits the change and adds it to the merge queue. If possible the | |
| change is merged into the destination branch. | |
| + | |
| The `Submit` button is available if the change is submittable and | |
| the link:access-control.html#category_submit[Submit] access right is | |
| assigned. | |
| ** [[revert]]`Revert`: | |
| + | |
| Reverts the change via creating a new one. | |
| + | |
| The `Revert` button is available if the change has been submitted. | |
| + | |
| When the `Revert` button is pressed, a panel will appear to allow | |
| the user to enter a commit message for the reverting change. | |
| + | |
| Once a revert change is created, the original author and any reviewers | |
| of the original change are added as reviewers and a message is posted | |
| to the original change linking to the revert. | |
| ** [[abandon]]`Abandon`: | |
| + | |
| Abandons the change. | |
| + | |
| The `Abandon` button is only available if the change is open and the | |
| link:access-control.html#category_abandon[Abandon] access right is | |
| assigned. | |
| + | |
| When a change is abandoned, a panel appears that allows one to type a | |
| comment message to explain why the change is being abandoned. | |
| ** [[restore]]`Restore`: | |
| + | |
| Restores the change. | |
| + | |
| The `Restore` button is only available if the change is abandoned and | |
| the link:access-control.html#category_abandon[Abandon] and the | |
| link:access-control.html#category_push[Push] access right is | |
| assigned. | |
| + | |
| When a change is restored, a panel appears that allows one to type a | |
| comment message to explain why the change is being restored. | |
| ** [[rebase]]`Rebase`: | |
| + | |
| Rebases the change. The rebase is always done with content merge | |
| enabled. If the rebase is successful a new patch set with the rebased | |
| commit is created. If the rebase fails, there are conflicts that have | |
| to be resolved manually. | |
| + | |
| If the change does not depend on another open change, it is rebased | |
| onto the tip of the destination branch. | |
| + | |
| If the change depends on another open change, it is rebased onto the | |
| current patch set of that other change. | |
| + | |
| It is possible to change parent revision of a change. The new parent | |
| revision can be another change towards the same target branch, or | |
| the tip of the target branch. | |
| + | |
| The `Rebase` button is only available if | |
| the link:access-control.html#category_rebase[Rebase] access right is | |
| assigned. Rebasing merge commits is not supported. | |
| ** [[cherry-pick]]`Cherry-Pick`: | |
| + | |
| Allows to cherry-pick the change to another branch. The destination | |
| branch can be selected from a dialog. Cherry-picking a change creates a | |
| new open change on the selected destination branch. | |
| + | |
| It is also possible to cherry-pick a change to the same branch. This is | |
| effectively the same as rebasing it to the current tip of the | |
| destination branch. This can be used to remove dependencies on other | |
| open changes. | |
| + | |
| Users can only cherry-pick changes to branches for which they are | |
| allowed to upload changes for review. | |
| ** [[delete]]`Delete Change` / `Delete Revision`: | |
| + | |
| Deletes the change. | |
| + | |
| For open or abandoned changes, the `Delete Change` button will be available | |
| and if the user is the change owner and is granted the | |
| link:access-control.html#category_delete_own_changes[Delete Own Changes] | |
| permission, if they are granted the | |
| link:access-control.html#category_delete_changes[Delete Changes] permission, | |
| or if they are an administrator. | |
| ** [[plugin-actions]]Further actions may be available if plugins are installed. | |
| + | |
| image::images/user-review-ui-change-screen-change-info-actions.png[width=400, link="images/user-review-ui-change-screen-change-info-actions.png"] | |
| [[files-tab]] | |
| === File List | |
| The file list shows the files that are modified in the currently viewed | |
| patch set. | |
| image::images/user-review-ui-change-screen-file-list.png[width=800, link="images/user-review-ui-change-screen-file-list.png"] | |
| [[magic-files]] | |
| In addition to the modified files the file list contains magic files | |
| that are generated by Gerrit and which don't exist in the repository. | |
| The magic files contain additional commit data that should be | |
| reviewable and allow users to comment on this data. The magic files are | |
| always listed first. The following magic files exist: | |
| * `Commit Message`: | |
| + | |
| The commit message and headers with the parent commit(s), the author | |
| information and the committer information. | |
| * `Merge List` (for merge commits only): | |
| + | |
| The list of commits that are being integrated into the destination | |
| branch by submitting the merge commit. | |
| Every file is accompanied by a number of extra information, such as status | |
| (modified, added, deleted, etc.), number of changed lines, type (executable, | |
| link, plain), comments and others. Hovering over most icons and columns reveals | |
| additional information. | |
| Each file can be expanded to view the contents of the file and diff. For more | |
| information see <<diff-view, Diff View>> section. | |
| [[comments-tab]] | |
| === Comments Tab | |
| Instead of the file list, a comments tab can be selected. Comments tab presents | |
| comments along with related file/diff snippets. It also offers some filtering | |
| opportunities at the top (ex. only unresolved, only comments from user X, etc.) | |
| image::images/user-review-ui-change-screen-comments-tab.png[width=800, link="images/user-review-ui-change-screen-comments-tab.png"] | |
| [[checks-tab]] | |
| === Checks Tab | |
| Checks tab contains results of different "Check Runs" installed by plugins. For | |
| more information see link:pg-plugin-checks-api.html[Checks API] page. | |
| [[patch-sets]] | |
| === Patch Sets | |
| The change screen only presents one pair of patch sets (`Patchset A` and | |
| `Patchset B`) at a time. `A` is always an earlier upload than `B` and serves as | |
| a base for diffing when viewing changes in the files. Which patch | |
| sets is currently viewed can be seen from the `Patch Sets` drop-down | |
| panel in the change header. If patchset 'A' is not selected a parent commit of | |
| patchset 'B' is used by default. | |
| image::images/user-review-ui-change-screen-patch-sets.png[width=300, link="images/user-review-ui-change-screen-patch-sets.png"] | |
| [[download]] | |
| === Download | |
| The `Download` drop-down panel in the change header offers commands and | |
| links for downloading the currently viewed patch set. | |
| image::images/user-review-ui-change-screen-download-commands.png[width=800, link="images/user-review-ui-change-screen-download-commands.png"] | |
| The available download commands depend on the installed Gerrit plugins. | |
| The most popular plugin for download commands, the | |
| link:https://gerrit-review.googlesource.com/admin/repos/plugins/download-commands[ | |
| download-commands,role=external,window=_blank] plugin, provides commands to checkout, pull and | |
| cherry-pick a patch set. | |
| Each command has a copy-to-clipboard icon that allows the command to be | |
| copied into the clipboard. This makes it easy to paste and execute the | |
| command on a Git command line. Additionally each line can copied to clipboard | |
| using number (1..9) of the appropriate line as a keyboard shortcut. | |
| If several download schemes are configured on the server (e.g. SSH and | |
| HTTP) there is a drop-down list to switch between the download schemes. | |
| Gerrit automatically remembers the download scheme that was last chosen | |
| and selects this download scheme the next time the download commands | |
| drop-down panel is opened. | |
| The `Patch-File` links provide the Git patch file for the currently | |
| viewed patch set for download. The patch file can be base64 encoded or | |
| zipped. | |
| The `Archive` links allow one to download an archive with the contents | |
| of the currently viewed patch set. The archive is offered in several | |
| formats (e.g. tar and tbz2); which formats are available depends on the | |
| configuration of the server. | |
| [[included-in]] | |
| === Included In | |
| For merged changes the `Included In` drop-down panel is available | |
| through the overflow menu at the top. It shows the branches and tags | |
| in which the change is included. E.g. if a change fixes a bug, this | |
| shows which released versions contain the bug-fix (assuming that every | |
| release is tagged). | |
| image::images/user-review-ui-change-screen-included-in.png[width=800, link="images/user-review-ui-change-screen-included-in.png"] | |
| [[related-changes]] | |
| === Related Changes | |
| If there are changes that are related to the currently viewed change | |
| they are displayed in the third column of the change screen. | |
| There are several lists of related changes that are displayed in separate | |
| sectionsunder each other. | |
| The following sections may be displayed: | |
| - [[related-changes-section]]`Related Changes`: | |
| + | |
| This section shows changes on which the current change depends | |
| (ancestors) and open changes that depend on the current change | |
| (descendants). For merge commits it also shows the closed changes that | |
| will be merged into the destination branch by submitting the merge | |
| commit. | |
| + | |
| The changes are sorted in the same way as the output of 'git log'. This | |
| means the relationship between the changes can be inferred from the | |
| position of the changes in the list. Changes listed above the current | |
| change are descendants; changes below the current change are ancestors. | |
| + | |
| For merged changes this tab is only shown if there are open | |
| descendants. | |
| + | |
| Related changes may be annotated with dependencies | |
| on outdated patch sets, or commits that are not associated to changes | |
| under review: | |
| + | |
| ** [[not-current]]Not current: | |
| + | |
| The patch set of the related change which is related to the current change is | |
| outdated; it is not the current patch set of the change. | |
| + | |
| For ancestor it means that the | |
| currently viewed patch set depends on a outdated patch set of the | |
| ancestor change. This is because a new patch set for the ancestor | |
| change was uploaded in the meantime and as result the currently viewed | |
| patch set now needs to be rebased. | |
| + | |
| If a descendant change is marked "not current" it means that an | |
| old patch set of the descendant change depends on the currently viewed | |
| patch set. It may be that the descendant was rebased in the meantime | |
| and with the new patch set this dependency was removed. | |
| ** [[indirect-descendant]]Indirect descendant: | |
| + | |
| The selected patch set of the change is an indirect descendant of the | |
| currently viewed patch set; it has a dependency to another patch set of | |
| this change. E.g. this could mean that a new patch set was uploaded for | |
| this change and the descendant change now needs to be rebased. Please | |
| note that following the link to an indirect descendant change may | |
| result in a completely different related changes listing. | |
| ** [[merged-related-change]]Merged | |
| + | |
| The change has been merged. | |
| + | |
| If the relationship to submitted change falls under conditions described in | |
| <<not-current, Not current>> the status is orange. Such changes can appear as | |
| both ancestors and descendants of the change. | |
| ** [[submittable-related-change]]Submittable | |
| + | |
| All the submit requirements are fulfilled for the related change and it can be | |
| submitted when all of its ancestors are submitted. | |
| ** [[closed-ancestor-abandoned]]Abandoned: | |
| + | |
| Indicates an abandoned change. | |
| - [[conflicts-with]]`Merge Conflicts`: | |
| + | |
| This section shows changes that conflict with the current change. | |
| Non-mergeable changes are filtered out; only conflicting changes that | |
| are mergeable are shown. | |
| + | |
| If this change is merged, its conflicting changes will have merge | |
| conflicts and must be rebased. The rebase of the other changes with the | |
| conflict resolution must then be done manually. | |
| - [[submitted-together]]`Submitted Together`: | |
| + | |
| This section shows changes that will be submitted together with the | |
| currently viewed change, when clicking the submit button. It includes | |
| ancestors of the current patch set. | |
| + | |
| If `change.submitWholeTopic` is enabled this section also includes changes with | |
| the same topic. The list recursively includes all changes that can be reached by | |
| ancestor and topic relationships. Only open changes are included in the result. | |
| - [[cherry-picks]]`Cherry-Picks`: | |
| + | |
| This section shows changes with the same link:user-changeid.html[ | |
| Change-Id] for the current project. | |
| + | |
| Abandoned changes are filtered out. | |
| + | |
| For each change in this list the destination branch is shown as a | |
| prefix in front of the change subject. | |
| + | |
| If there are no related changes for a tab, the tab is not displayed. | |
| - [[same-topic]]`Same Topic`: | |
| + | |
| This section shows changes which are part of the same topic. If | |
| `change.submitWholeTopic` is enabled, then this section is omitted and changes | |
| are included as part of <<submitted-together, `Submitted Together`>> | |
| [[reply]] | |
| === Reply | |
| The `Reply...` button in the change header allows to reply to the | |
| currently viewed patch set; one can add a summary comment, publish | |
| inline draft comments, vote on the labels and adjust attention set. | |
| image::images/user-review-ui-change-screen-reply.png[width=800, link="images/user-review-ui-change-screen-reply.png"] | |
| Clicking on the `Reply...` button opens a popup panel. | |
| [[summary-comment]] | |
| A text box allows to type a summary comment for the currently viewed | |
| patch set. Markdown syntax is supported same as in other | |
| <<comments-markdown, Comments>>. | |
| [[vote]] | |
| If the current patch set is viewed, buttons are displayed for | |
| each label on which the user is allowed to vote. Voting on non-current | |
| patch sets is not possible. | |
| The inline draft comments that will be published are displayed in a | |
| separate section so that they can be reviewed before publishing. There | |
| are links to navigate to the inline comments which can be used if a | |
| comment needs to be edited. | |
| The `SEND` button publishes the comments and the votes. | |
| [[quick-approve]] | |
| If a user can approve a label that is still required, a quick approve | |
| button appears in the change header that allows to add this missing | |
| approval by a single click. The quick approve button only appears if | |
| there is a single label that is still required and can be approved by | |
| the user. | |
| E.g. if a change requires approvals on the 'Code-Review' and the | |
| 'Verified' labels, and there is already a '+1 Verified' vote, then | |
| if the user is allowed to vote the max score on 'Code-Review', a | |
| `Code-Review+2` quick approve button appears that approves the | |
| 'Code-Review' label if clicked. | |
| Using the quick approve button also publishes all inline draft | |
| comments; a summary comment is only added if the reply popup panel is | |
| open when the quick approve button is clicked. | |
| image::images/user-review-ui-change-screen-quick-approve.png[width=800, link="images/user-review-ui-change-screen-quick-approve.png"] | |
| [[change-log]] | |
| === Change Log | |
| The history of the change can be seen in the lower part of the screen. | |
| The log contains messages for all kinds of change updates, e.g. a | |
| message is added when a new patch set is uploaded or when a review was | |
| done. | |
| [[update-notification]] | |
| === Update Notification | |
| The change screen automatically polls for updates to the currently | |
| viewed change. If there is an update the user is informed by a popup | |
| panel in the bottom right corner. | |
| The polling frequency depends on the server configuration; by default | |
| it is 30 seconds. Polling may also be completely disabled by the | |
| administrator. | |
| image::images/user-review-ui-change-screen-change-update.png[width=400, link="images/user-review-ui-change-screen-change-update.png"] | |
| [[plugin-extensions]] | |
| === Plugin Extensions | |
| Gerrit plugins may extend the change screen. Java plugins in the | |
| backend can add additional actions to the triple-dot menu block. | |
| Frontend plugins can change the UI controls in arbitrary ways. | |
| image::images/user-review-ui-change-screen-plugin-extensions.png[width=300, link="images/user-review-ui-change-screen-plugin-extensions.png"] | |
| [[diff-view]] | |
| == Side-by-Side Diff Screen | |
| The side-by-side diff screen shows a single patch (or difference between two | |
| patchsets); the old file version is displayed on the left side of the screen; | |
| the new file version is displayed on the right side of the screen. | |
| This screen allows to review a patch and to comment on it. | |
| image::images/user-review-ui-side-by-side-diff-screen.png[width=800, link="images/user-review-ui-side-by-side-diff-screen.png"] | |
| [[side-by-side-mark-reviewed]] | |
| The checkbox in front of the file name allows the | |
| patch to be marked as reviewed. The link:#mark-reviewed[Mark Reviewed] | |
| diff preference allows to control whether the files should be | |
| automatically marked as reviewed when they are viewed. | |
| image::images/user-review-ui-side-by-side-diff-screen-reviewed.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-reviewed.png"] | |
| [[patch-set-selection]] | |
| In the header, on each side, the list of patch sets is shown. Clicking | |
| on a patch set changes the selection for the patch set comparison and | |
| the screen is refreshed to show the diff between the selected patch | |
| sets. The currently selected patch set is highlighted by a light blue | |
| background. | |
| On the left side `Base` can be selected to compare a patch set against | |
| its base. For merge commits `Auto Merge` is available instead which | |
| allows to compare the patch against the result of the auto merge. The | |
| auto merge version may contain Git conflict markers and is useful for | |
| reviewing how conflicts are resolved by a patch. | |
| Reviewers that are reviewing a patch for the first time look at its | |
| diff against its base; reviewers that have reviewed an old patch | |
| version before, may see what has changed since that version by | |
| comparing the old patch against the current patch. | |
| image::images/user-review-ui-side-by-side-diff-screen-patch-sets.png[width=400, link="images/user-review-ui-side-by-side-diff-screen-patch-sets.png"] | |
| [[download-file]] | |
| The download icon next to the patch set list allows to download the | |
| patch. Unless the mime type of the file is configured as safe, the | |
| download file is a zip archive that contains the patch file. | |
| [[side-by-side-rename]] | |
| If a file was renamed, the old and new file paths are shown in the | |
| header together with a similarity index that shows how much of the file | |
| content is unmodified. | |
| image::images/user-review-ui-side-by-side-diff-screen-rename.png[width=400, link="images/user-review-ui-side-by-side-diff-screen-rename.png"] | |
| [[inline-comments]] | |
| === Inline Comments | |
| Inline comments are displayed directly in the patch file under the code | |
| that is commented. Inline comments can be placed on lines or on code | |
| blocks. | |
| If an inline comment relates to a code block, this code block is | |
| highlighted by a yellow background. | |
| Code blocks with comments may overlap. This means it is possible to | |
| attach several comments to the same code. | |
| [[comments-markdown]] | |
| The comments support markdown. It follows the CommonMark spec, except inline | |
| images and direct HTML are not rendered and kept as plaintext. | |
| [[line-links]] | |
| The lines of the patch file are linkable: simply append | |
| '#<linenumber>' to the URL, or click on the line-number. This not only | |
| opens a draft comment box, but also sets the URL fragment. | |
| [[reply-inline-comment]] | |
| Clicking on the `Reply` button opens an editor to type the reply. | |
| Previous comment can be quoted using "Quote" button. A new draft would be open | |
| on the same comment thread with the text of the previoused comment quoted using | |
| markdown syntax. | |
| image::images/user-review-ui-side-by-side-diff-screen-inline-comments.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-inline-comments.png"] | |
| Comments are first saved as drafts, and you can revisit the drafts as | |
| you read through code review. Finally, they will be published by | |
| clicking the "Reply". | |
| [[done]] | |
| Comments can be unresolved (something should be changed) or resolved | |
| (informational). If you have addressed an unresolved comment in a next | |
| patchset, you can quickly resolve the comment by clicking "Done" (if it was | |
| resolved in a next patchset) or "Ack" (if you acknowledge the comment, | |
| but don't want to make changes). | |
| image::images/user-review-ui-side-by-side-diff-screen-replied-done.png[width=400, link="images/user-review-ui-side-by-side-diff-screen-replied-done.png"] | |
| [[add-inline-comment]] | |
| To add a new inline comment there are several possibilities: | |
| - select a code block and press 'c' | |
| - go to a line, by clicking on it or by link:#key-navigation[key | |
| navigation], and press 'c' | |
| - click on a line number | |
| There are many ways to select code for commenting on it. The most | |
| frequently used methods are: | |
| - by mouse: | |
| ** click and drag with the mouse to select a block | |
| ** double-click on a word to select it | |
| ** double-click and drag with the mouse to select a code block word-wise | |
| ** triple-click on a line to select it | |
| ** triple-click and drag with the mouse to select a code block line-wise | |
| For typing the new comment, a new comment box is shown under the code | |
| that is commented. | |
| Clicking on the `Save` button saves the new comment as a draft. To | |
| make it visible to other users it must be published from the change | |
| screen by link:#reply[replying] to the change. | |
| [[suggest-fix]] | |
| === Suggest fix (WIP) | |
| Comments can contain suggested fixes. | |
| Clicking "Suggest Fix" will insert a special code-block in the text of the | |
| comment. The contents of this code block will replace the lines the comment is | |
| attached to (what gets highlighted when hovering over comment). | |
| image::images/user-review-ui-suggest-fix.png[width=400, link="images/user-review-ui-suggest-fix.png"] | |
| The author of the change can then preview and apply the change. This will created | |
| a new patchset with changes applied. | |
| image::images/user-review-ui-apply-fix.png[width=800, link="images/user-review-ui-apply-fix.png"] | |
| [[file-level-comments]] | |
| === File Level Comments | |
| File level comments are added by clicking the 'File' header at the top | |
| of the file. | |
| image::images/user-review-ui-side-by-side-diff-screen-file-level-comment.png[width=400, link="images/user-review-ui-side-by-side-diff-screen-file-level-comment.png"] | |
| [[diff-preferences]] | |
| === Diff Preferences | |
| There are several options to control how patch diffs should be | |
| rendered. Users can configure their preferences in the diff | |
| preferences. The diff preferences can be accessed by clicking on the | |
| settings icon in the screen header. | |
| image::images/user-review-ui-side-by-side-diff-screen-preferences.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-preferences.png"] | |
| The following diff preferences can be configured: | |
| - [[ignore-whitespace]]`Ignore Whitespace`: | |
| + | |
| Controls whether differences in whitespace should be ignored or not. | |
| + | |
| ** `None`: | |
| + | |
| All differences in whitespace are highlighted. | |
| + | |
| ** `Trailing`: | |
| + | |
| Whitespace differences at the end of lines are ignored. | |
| + | |
| ** `Leading, Trailing`: | |
| + | |
| Whitespace differences at the beginning and end of lines are ignored. | |
| + | |
| ** `All`: | |
| + | |
| All differences in whitespace are ignored. | |
| - [[tab-width]]`Tab Width`: | |
| + | |
| Controls how many spaces should be displayed for a tab. | |
| - [[columns]]`Columns`: | |
| + | |
| Sets the preferred line length. At this position, lines are wrapped. | |
| - [[lines-of-context]]`Lines Of Context`: | |
| + | |
| The number of context lines that should be displayed before and after | |
| any diff. If the `entire file` checkbox is selected, the full file is | |
| rendered. | |
| + | |
| Skipped common lines can be expanded by clicking on the placeholder for | |
| the skipped lines. | |
| + | |
| Clicking on "... skipped <n> common lines ..." expands the complete | |
| block of skipped lines. | |
| + | |
| If many lines are skipped there are additional links to expand the | |
| context by ten lines before and after the skipped block. | |
| + | |
| image::images/user-review-ui-side-by-side-diff-screen-expand-skipped-lines.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-expand-skipped-lines.png"] | |
| - [[syntax-highlighting]]`Syntax Highlighting`: | |
| + | |
| Controls whether syntax highlighting should be enabled. | |
| + | |
| The language for the syntax highlighting is automatically detected from | |
| the file extension. | |
| - [[whitespace-errors]]`Show trailing whitespace`: | |
| + | |
| Controls whether trailing whitespace is highlighted. | |
| - [[show-tabs]]`Show Tabs`: | |
| + | |
| Controls whether tabs are highlighted. | |
| - [[mark-reviewed]]`Mark Reviewed`: | |
| + | |
| Controls whether the files of the patch set should be automatically | |
| marked as reviewed when they are viewed. | |
| [[keyboard-shortcuts]] | |
| == Keyboard Shortcuts | |
| Navigation within the review UI can be completely done by keys, and | |
| most actions can be controlled by keyboard shortcuts. Typing `?` opens | |
| a popup that shows a list of available keyboard shortcuts. | |
| image::images/user-review-ui-change-screen-keyboard-shortcuts.png[width=800, link="images/user-review-ui-change-screen-keyboard-shortcuts.png"] | |
| In addition, Vim-like commands can be used to link:#key-navigation[ | |
| navigate] and link:#search[search] within a patch file. | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] | |
| SEARCHBOX | |
| --------- |