| = Review UI |
| |
| Reviewing changes is an important task and the Gerrit Web UI provides |
| many functionalities to make the review process comfortable and |
| efficient. This is a guide through the review UI that explains the |
| different functions and UI elements. |
| |
| [[change-screen]] |
| == Change Screen |
| |
| The change screen shows the details of a single change and provides |
| various actions on it. |
| |
| image::images/user-review-ui-change-screen.png[width=800, link="images/user-review-ui-change-screen.png"] |
| |
| [[commit-message]] |
| === Commit Message Block |
| |
| The focus of the change screen is on the commit message since this is |
| the most important information about a change. The numeric change ID |
| and the change status are displayed right above the commit message. |
| |
| image::images/user-review-ui-change-screen-commit-message.png[width=800, link="images/user-review-ui-change-screen-commit-message.png"] |
| |
| [[permalink]] |
| The numeric change ID is a link to the change and clicking on it |
| refreshes the change screen. By copying the link location you can get |
| the permalink of the change. |
| |
| image::images/user-review-ui-change-screen-permalink.png[width=800, link="images/user-review-ui-change-screen-permalink.png"] |
| |
| [[change-status]] |
| The change status shows the state of the change: |
| |
| - [[needs]]`Needs <label>`: |
| + |
| The change is in review and an approval on the shown label is still |
| required to make the change submittable. |
| |
| - [[not]]`Not <label>`: |
| + |
| The change is in review and a veto vote on the shown label is |
| preventing the submit. |
| |
| - [[not-current]]`Not Current`: |
| + |
| The currently viewed patch set is outdated. |
| + |
| Please note that some operations, like voting, are not available on |
| outdated patch sets, but only on the current patch set. |
| |
| - [[ready-to-submit]]`Ready to Submit`: |
| + |
| The change has all necessary approvals and may be submitted. |
| |
| - [[merged]]`Merged`: |
| + |
| The change was successfully merged into the destination branch. |
| |
| - [[abandoned]]`Abandoned`: |
| + |
| The change was abandoned. |
| |
| - [[draft]]`Draft`: |
| + |
| The change is a draft that is only visible to the change owner, the |
| reviewers that were explicitly added to the change, and users who have |
| the link:access-control.html#category_view_drafts[View Drafts] global |
| capability assigned. |
| |
| [[commit-info]] |
| === Commit Info Block |
| |
| The commit info block shows information about the commit of the |
| currently viewed patch set. |
| |
| It displays the author and the committer as links to a list of this |
| person's changes that have the same status as the currently viewed |
| change. |
| |
| The commit ID, the parent commit(s) and the link:user-changeid.html[Change-Id] are |
| displayed with a copy-to-clipboard icon that allows the ID to be copied |
| into the clipboard. |
| |
| If a Git web browser, such as gitweb or Gitiles, is configured, there |
| is also a link to the commit in the Git web browser. |
| |
| image::images/user-review-ui-change-screen-commit-info.png[width=800, link="images/user-review-ui-change-screen-commit-info.png"] |
| |
| If a merge commit is viewed this is highlighted by an icon. |
| |
| image::images/user-review-ui-change-screen-commit-info-merge-commit.png[width=800, link="images/user-review-ui-change-screen-commit-info-merge-commit.png"] |
| |
| [[change-info]] |
| === Change Info Block |
| |
| The change info block contains detailed information about the change |
| and offers actions on the change. |
| |
| image::images/user-review-ui-change-screen-change-info.png[width=800, link="images/user-review-ui-change-screen-change-info.png"] |
| |
| - [[change-owner]]Change Owner: |
| + |
| The owner of the change is displayed as a link to a list of the owner's |
| changes that have the same status as the currently viewed change. |
| + |
| image::images/user-review-ui-change-screen-change-info-owner.png[width=800, link="images/user-review-ui-change-screen-change-info-owner.png"] |
| |
| - [[reviewers]]Reviewers: |
| + |
| The reviewers of the change are displayed as chip tokens. |
| + |
| For each reviewer there is a tooltip that shows on which labels the |
| reviewer is allowed to vote. |
| + |
| New reviewers can be added by clicking on the `Add...` button. Typing |
| into the pop-up text field activates auto completion of user and group |
| names. |
| + |
| [[remove-reviewer]] |
| Reviewers can be removed from the change by clicking on the `x` icon |
| in the reviewer's chip token. Removing a reviewer also removes the |
| current votes of the reviewer. The removal of votes is recorded as a |
| message on the change. |
| + |
| 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. |
| |
| + |
| image::images/user-review-ui-change-screen-change-info-reviewers.png[width=800, link="images/user-review-ui-change-screen-change-info-reviewers.png"] |
| |
| - [[project-branch-topic]]Project / 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. |
| + |
| Clicking on the settings icon on the right side navigates to the |
| project administration screen. |
| + |
| 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. |
| + |
| image::images/user-review-ui-change-screen-change-info-project-branch-topic.png[width=800, link="images/user-review-ui-change-screen-change-info-project-branch-topic.png"] |
| |
| - [[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. |
| + |
| image::images/user-review-ui-change-screen-change-info-submit-strategy.png[width=800, link="images/user-review-ui-change-screen-change-info-submit-strategy.png"] |
| + |
| If a change cannot be merged due to path conflicts this is highlighted |
| by a bold red `Cannot Merge` label. |
| + |
| image::images/user-review-ui-change-screen-change-info-cannot-merge.png[width=800, link="images/user-review-ui-change-screen-change-info-cannot-merge.png"] |
| |
| - [[update-time]]Time of Last Update: |
| + |
| image::images/user-review-ui-change-screen-change-info-last-update.png[width=800, link="images/user-review-ui-change-screen-change-info-last-update.png"] |
| |
| - [[actions]]Actions: |
| + |
| 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. |
| + |
| It is also possible to submit changes that have merge conflicts. This |
| allows to do the conflict resolution for a change series in a single |
| merge commit and submit the changes in reverse order. |
| |
| ** [[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. |
| |
| ** [[publish]]`Publish`: |
| + |
| Publishes the currently viewed draft patch set. If this is the first |
| patch set of a change that is published, the change will be published |
| as well. |
| + |
| The `Publish` button is only available if a draft patch set is viewed |
| and the user is the change owner or has the |
| link:access-control.html#category_publish_drafts[Publish Drafts] access |
| right assigned. |
| |
| ** [[delete]]`Delete Change` / `Delete Revision`: |
| + |
| Deletes the draft change / the currently viewed draft patch set. |
| + |
| The `Delete Change` / `Delete Revision` buttons are only available if a |
| draft patch set is viewed and the user is the change owner or has the |
| link:access-control.html#category_delete_drafts[Delete Drafts] access |
| right assigned. |
| |
| ** [[plugin-actions]]Further actions may be available if plugins are installed. |
| |
| + |
| image::images/user-review-ui-change-screen-change-info-actions.png[width=800, link="images/user-review-ui-change-screen-change-info-actions.png"] |
| |
| - [[labels]]Labels & Votes: |
| + |
| Approving votes are colored green; veto votes are colored red. |
| + |
| image::images/user-review-ui-change-screen-change-info-labels.png[width=800, link="images/user-review-ui-change-screen-change-info-labels.png"] |
| |
| [[files]] |
| === 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"] |
| |
| [[change-screen-mark-reviewed]] |
| The checkboxes in front of the file names allow files to be marked as reviewed. |
| |
| image::images/user-review-ui-change-screen-file-list-mark-as-reviewed.png[width=800, link="images/user-review-ui-change-screen-file-list-mark-as-reviewed.png"] |
| |
| [[modification-type]] |
| The type of a file modification is indicated by the character in front |
| of the file name: |
| |
| - 'no character' (Modified): |
| + |
| The file existed before this change and is modified. |
| |
| - `A` (Added): |
| + |
| The file is newly added. |
| |
| - `D` (Deleted): |
| + |
| The file is deleted. |
| |
| - `R` (Renamed): |
| + |
| The file is renamed. |
| |
| - `C` (Copied): |
| + |
| The file is new and is copied from an existing file. |
| |
| image::images/user-review-ui-change-screen-file-list-modification-type.png[width=800, link="images/user-review-ui-change-screen-file-list-modification-type.png"] |
| |
| [[rename-or-copy]] |
| If a file is renamed or copied, the name of the original file is |
| displayed in gray below the file name. |
| |
| image::images/user-review-ui-change-screen-file-list-rename.png[width=800, link="images/user-review-ui-change-screen-file-list-rename.png"] |
| |
| [[repeating-path-segments]] |
| Repeating path segments are grayed out. |
| |
| image::images/user-review-ui-change-screen-file-list-repeating-paths.png[width=800, link="images/user-review-ui-change-screen-file-list-repeating-paths.png"] |
| |
| [[inline-comments-column]] |
| Inline comments on a file are shown in the `Comments` column. |
| |
| Draft comments, i.e. comments that have been written by the current |
| user but not yet published, are highlighted in red. |
| |
| New comments from other users, that were published after the current |
| user last reviewed this change, are highlighted in bold. |
| |
| image::images/user-review-ui-change-screen-file-list-comments.png[width=800, link="images/user-review-ui-change-screen-file-list-comments.png"] |
| |
| [[size]] |
| The size of the modifications in the files can be seen in the `Size` column. The |
| footer row shows the total size of the change. |
| |
| The size information is useful to easily spot the files that contain |
| the most modifications; these files are likely to be the most relevant |
| files for this change. The total change size gives an estimate of how |
| long a review of this change may take. |
| |
| When the "Show Change Sizes As Colored Bars" user preference is enabled, the |
| `Size` column shows the sum of inserted and deleted lines as one number. In |
| addition, the change size is shown as a bar. The size of the bar indicates the |
| amount of changed lines, and its coloring shows the proportion of insertions |
| (green) to deletions (red). |
| |
| When the "Show Change Sizes As Colored Bars" user preference is disabled, the |
| colored bar is not shown. For added and renamed files, the `Size` column |
| shows the number of inserted and deleted lines. For new files, the column only |
| shows the total number of lines in the new file. No size is shown for binary |
| files and deleted files. |
| |
| image::images/user-review-ui-change-screen-file-list-size.png[width=800, link="images/user-review-ui-change-screen-file-list-size.png"] |
| |
| [[diff-against]] |
| In the header of the file list, the `Diff Against` selection can be |
| changed. This selection allows one to choose if the currently viewed |
| patch set should be compared against its base or against another patch |
| set of this change. The file list is updated accordingly. |
| |
| [[open-all]] |
| The file list header also provides an `Open All` button that opens the |
| diff views for all files in the file list. |
| |
| image::images/user-review-ui-change-screen-file-list-header.png[width=800, link="images/user-review-ui-change-screen-file-list-header.png"] |
| |
| [[patch-sets]] |
| === Patch Sets |
| |
| The change screen only presents one patch set at a time. Which patch |
| set is currently viewed can be seen from the `Patch Sets` drop-down |
| panel in the change header. It shows the number of the currently viewed |
| patch set and the total number of patch sets, in the form: "current |
| patch set/number of patch sets". |
| |
| If a non-current patch set is viewed this is indicated by the |
| link:#not-current[Not Current] change state. Please note that some |
| operations are only available on the current patch set. |
| |
| image::images/user-review-ui-change-screen-patch-sets.png[width=800, link="images/user-review-ui-change-screen-patch-sets.png"] |
| |
| [[patch-set-drop-down]] |
| The patch set drop-down list shows the list of patch sets and allows to |
| switch between them. The patch sets are sorted in descending order so |
| that the current patch set is always on top. |
| |
| Draft patch sets are marked with `DRAFT`. |
| |
| image::images/user-review-ui-change-screen-patch-set-list.png[width=800, link="images/user-review-ui-change-screen-patch-set-list.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/projects/plugins/download-commands[ |
| download-commands] 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. |
| |
| 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. |
| |
| image::images/user-review-ui-change-screen-download-commands-list.png[width=800, link="images/user-review-ui-change-screen-download-commands-list.png"] |
| |
| [[included-in]] |
| === Included In |
| |
| For merged changes the `Included In` drop-down panel is available in |
| the change header. |
| |
| image::images/user-review-ui-change-screen-included-in.png[width=800, link="images/user-review-ui-change-screen-included-in.png"] |
| |
| The `Included In` drop-down panel shows the branches and tags in which |
| the change is included. E.g. if a change fixes a bug, this allows to |
| quickly see in which released versions the bug-fix is contained |
| (assuming that every release is tagged). |
| |
| image::images/user-review-ui-change-screen-included-in-list.png[width=800, link="images/user-review-ui-change-screen-included-in-list.png"] |
| |
| [[star]] |
| === Star Change |
| |
| The star icon in the change header allows to mark the change as a |
| favorite. Clicking on the star icon again, unstars the change. |
| |
| image::images/user-review-ui-change-screen-star.png[width=800, link="images/user-review-ui-change-screen-star.png"] |
| |
| Starring a change turns on email notifications for this change. |
| |
| Starred changed are listed under `My` > `Starred Changes`. |
| and can be queried by the link:user-search.html#is[is:starred] search |
| operator. |
| |
| [[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 and a tab control is used to |
| display each list of related changes in its own tab. |
| |
| The following tabs may be displayed: |
| |
| - [[related-changes-tab]]`Related Changes`: |
| + |
| This tab page 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. |
| + |
| image::images/user-review-ui-change-screen-related-changes.png[width=800, link="images/user-review-ui-change-screen-related-changes.png"] |
| + |
| Related changes may be decorated with an icon to signify dependencies |
| on outdated patch sets, or commits that are not associated to changes |
| under review: |
| + |
| ** [[outdated]]Orange Dot: |
| + |
| The selected patch set of the change is outdated; it is not the current |
| patch set of the change. |
| + |
| If an ancestor change is marked with an orange dot 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 with an orange dot 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]]Green Tilde: |
| + |
| 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. |
| |
| ** [[closed-ancestor]]Black Dot: |
| + |
| Indicates a closed ancestor, e.g. the commit was directly pushed into |
| the repository bypassing code review, or the ancestor change was |
| reviewed and submitted on another branch. The latter may indicate that |
| the user has accidentally pushed the commit to the wrong branch, e.g. |
| the commit was done on `branch-a`, but was then pushed to |
| `refs/for/branch-b`. |
| A black dot is also present if the change was abandoned. |
| |
| ** [[closed-ancestor-abandoned]]Strikethrough Subject: |
| + |
| When the commit is abandoned, its subject line will be striked |
| through. |
| |
| + |
| image::images/user-review-ui-change-screen-related-changes-indicators.png[width=800, link="images/user-review-ui-change-screen-related-changes-indicators.png"] |
| |
| - [[conflicts-with]]`Conflicts With`: |
| + |
| This tab page 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. |
| + |
| image::images/user-review-ui-change-screen-conflicts-with.png[width=800, link="images/user-review-ui-change-screen-conflicts-with.png"] |
| |
| - [[same-topic]]`Same Topic`: |
| + |
| This tab page shows changes that have the same topic as the current |
| change. Only open changes are included in the list. |
| + |
| image::images/user-review-ui-change-screen-same-topic.png[width=800, link="images/user-review-ui-change-screen-same-topic.png"] |
| |
| - [[submitted-together]]`Submitted Together`: |
| + |
| This tab page 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. |
| + |
| This may include changes and its ancestors with the same topic if |
| `change.submitWholeTopic` is enabled. Only open changes with the |
| same topic are included in the list. |
| + |
| |
| - [[cherry-picks]]`Cherry-Picks`: |
| + |
| This tab page 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. |
| + |
| image::images/user-review-ui-change-screen-cherry-picks.png[width=800, link="images/user-review-ui-change-screen-cherry-picks.png"] |
| |
| If there are no related changes for a tab, the tab is not displayed. |
| |
| [[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, and vote on the labels. |
| |
| 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. |
| |
| A text box allows to type a summary comment for the currently viewed |
| patch set. |
| |
| Note that you can set the text and tooltip of the button in |
| link:config-gerrit.html#change.replyLabel[gerrit.config]. |
| |
| [[vote]] |
| If the current patch set is viewed, radio 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 `Post` button publishes the comments and the votes. |
| |
| image::images/user-review-ui-change-screen-replying.png[width=800, link="images/user-review-ui-change-screen-replying.png"] |
| |
| [[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"] |
| |
| [[history]] |
| === History |
| |
| The history of the change can be seen in the lower part of the screen. |
| |
| The history 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. |
| |
| Messages with new comments from other users, that were published after |
| the current user last reviewed this change, are automatically expanded. |
| |
| image::images/user-review-ui-change-screen-history.png[width=800, link="images/user-review-ui-change-screen-history.png"] |
| |
| [[reply-to-message]] |
| It is possible to directly reply to a change message by clicking on the |
| reply icon in the right upper corner of a change message. This opens |
| the reply popup panel and prefills the text box with the quoted comment. |
| Then the reply can be written below the quoted comment or inserted |
| inline. Lines starting with " > " will be rendered as a block quote. |
| Please note that for a correct rendering it is important to leave a blank |
| line between a quoted block and the reply to it. |
| |
| image::images/user-review-ui-change-screen-reply-to-comment.png[width=800, link="images/user-review-ui-change-screen-reply-to-comment.png"] |
| |
| [[inline-comments-in-history]] |
| Inline comments are directly displayed in the change history and there |
| are links to navigate to the inline comments. |
| |
| image::images/user-review-ui-change-screen-inline-comments.png[width=800, link="images/user-review-ui-change-screen-inline-comments.png"] |
| |
| [[expand-all]] |
| The `Expand All` button expands all messages; the `Collapse All` button |
| collapses all messages. |
| |
| [[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=800, link="images/user-review-ui-change-screen-change-update.png"] |
| |
| [[plugin-extensions]] |
| === Plugin Extensions |
| |
| Gerrit plugins may extend the change screen; they can add buttons for |
| additional actions to the change info block and display arbitrary UI |
| controls below the change info block. |
| |
| image::images/user-review-ui-change-screen-plugin-extensions.png[width=800, link="images/user-review-ui-change-screen-plugin-extensions.png"] |
| |
| [[side-by-side]] |
| == Side-by-Side Diff Screen |
| |
| The side-by-side diff screen shows a single patch; 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-header]] |
| In the screen header the project name and the name of the viewed patch |
| file are shown. |
| |
| If a Git web browser is configured on the server, the project name and |
| the file path are displayed as links to the project and the folder in |
| the Git web browser. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-project-and-file.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-project-and-file.png"] |
| |
| [[side-by-side-mark-reviewed]] |
| The checkbox in front of the project name and 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"] |
| |
| [[scrollbar]] |
| The scrollbar shows patch diffs and inline comments as annotations. |
| This provides a good overview of the lines in the patch that are |
| relevant for reviewing. By clicking on an annotation one can quickly |
| navigate to the corresponding line in the patch. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-scrollbar.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-scrollbar.png"] |
| |
| [[gaps]] |
| A gap between lines in the file content that is caused by aligning the |
| left and right side or by displaying inline comments is shown as a |
| vertical red bar in the line number column. This prevents a gap from |
| being mistaken for blank lines in the file |
| |
| image::images/user-review-ui-side-by-side-diff-screen-red-bar.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-red-bar.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=800, 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. |
| |
| [[no-differences]] |
| If the compared patches are identical, this is highlighted by a red |
| `No Differences` label in the screen header. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-no-differences.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-no-differences.png"] |
| |
| [[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=800, link="images/user-review-ui-side-by-side-diff-screen-rename.png"] |
| |
| [[navigation]] |
| For navigating between the patches in a patch set there are navigation |
| buttons on the right side of the screen header. The left arrow button |
| navigates to the previous patch; the right arrow button navigates to |
| the next patch. The arrow up button leads back to the change screen. In |
| all cases the selection for the patch set comparison is kept. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-navigation.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-navigation.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. |
| |
| [[line-links]] |
| The lines of the patch file are linkable. To link to a certain line in |
| the patch file, '@<line-number>' must be appended to the patch link, |
| e.g. `http://host:8080/#/c/56857/2/Documentation/user-review-ui.txt@665`. |
| To link to a line in the old file version, '@a<line-number>' must be |
| appended to the patch link. These links can be used to directly link to |
| certain inline comments. |
| |
| If the diff preference link:#expand-all-comments[Expand All Comments] |
| is set to `Expand`, all inline comments will be automatically expanded. |
| |
| 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"] |
| |
| [[comment]] |
| In the header of the comment box, the name of the comment author and |
| the timestamp of the comment are shown. If avatars are configured on |
| the server, the avatar image of the comment author is displayed in the |
| top left corner. Below the actual comment there are buttons to reply to |
| the comment. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-comment-box.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-comment-box.png"] |
| |
| [[reply-inline-comment]] |
| Clicking on the `Reply` button opens an editor to type the reply. |
| |
| Quoting is supported, but only by manually copying & pasting the old |
| comment that should be quoted and prefixing every line by " > ". Please |
| note that for a correct rendering it is important to leave a blank line |
| between a quoted block and the reply to it. |
| |
| Clicking on the `Save` button saves the 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. |
| |
| The `Cancel` button cancels the editing and discards any changes to the |
| draft comment. |
| |
| Clicking on the `Discard` button deletes the inline draft comment. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-comment-reply.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-comment-reply.png"] |
| |
| [[draft-inline-comment]] |
| Draft comments are marked by the text "Draft" in the header in the |
| place of the comment author. |
| |
| A draft comment can be edited by clicking on the `Edit` button, or |
| deleted by clicking on the `Discard` button. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-comment-edit.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-comment-edit.png"] |
| |
| [[done]] |
| Clicking on the `Done` button is a quick way to reply with "Done" to a |
| comment. This is used to mark a comment as addressed by a follow-up |
| patch set. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-replied-done.png[width=800, 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' |
| - select a code block and click on the popup comment icon |
| - 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 |
| |
| - by keys (the same keys that are used for visual selection in Vim): |
| ** press 'v' + arrow keys (or 'h', 'j', 'k', 'l') to select a block |
| ** press 'V' + arrow keys (or 'j', 'k') to select a code block line-wise |
| ** type 'bvw' to select a word |
| |
| image::images/user-review-ui-side-by-side-diff-screen-comment.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-comment.png"] |
| |
| 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. |
| |
| Clicking on the `Discard` button deletes the new comment. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-commented.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-commented.png"] |
| |
| [[file-level-comments]] |
| === File Level Comments |
| |
| Comments that apply to a whole file can be added on file level. |
| |
| File level comments are added by clicking on the comment icon in the |
| header above the file. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-file-level-comment.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-file-level-comment.png"] |
| |
| Clicking on the comment icon opens a comment box for typing the file |
| level comment. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-file-level-commented.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-file-level-commented.png"] |
| |
| [[search]] |
| === Search |
| |
| For searching within a patch file, a Vim-like search is supported. |
| Typing `/` opens the search box. Typing in the search box immediately |
| highlights matches in the patch file with a yellow background. Using |
| JavaScript regular expressions in the search term is supported. The |
| search is case insensitive. After confirming the search by `ENTER` one |
| can navigate between the matches by `n` / `N` to go to the next / |
| previous match. Skipped lines are automatically expanded if they |
| contain a match and one navigates to it. |
| |
| For additional possibilities to search please check the |
| link:http://www.vim.org/docs.php[Vim documentation]. There are other |
| useful ways to search, e.g. while the cursor is on a word, pressing `*` |
| or `#` searches for the next or previous occurrence of the word. |
| |
| Searching by `Ctrl-F` finds matches only in the visible area of the |
| screen unless the link:#render[Render] diff preference is set to `Slow`. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-search.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-search.png"] |
| |
| [[key-navigation]] |
| === Key Navigation |
| |
| Vim-like commands can be used to navigate within a patch file: |
| |
| - `h` / `j` / `k` / `l` moves the cursor left / down / up / right |
| - `0` / `$` moves the cursor to the start / end of the line |
| - `gg` / `G` moves to cursor to the start / end of the file |
| - `Ctrl-D` / `Ctrl-U` scolls downwards / upwards |
| |
| Please check the link:http://www.vim.org/docs.php[Vim documentation] |
| for further information. |
| |
| [[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 diff preferences popup allows to change the diff preferences. |
| By clicking on the `Save` button changes to the diff preferences are |
| saved permanently. Clicking on the `Apply` button applies the new |
| diff preferences to the current screen, but they are discarded when the |
| screen is refreshed. The `Save` button is only available if the user is |
| signed in. |
| |
| image::images/user-review-ui-side-by-side-diff-screen-preferences-popup.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-preferences-popup.png"] |
| |
| The following diff preferences can be configured: |
| |
| - [[theme]]`Theme`: |
| + |
| Controls the theme that is used to render the file content. |
| + |
| E.g. users could choose to work with a dark theme. |
| + |
| image::images/user-review-ui-side-by-side-diff-screen-dark-theme.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-dark-theme.png"] |
| |
| - [[ignore-whitespace]]`Ignore Whitespace`: |
| + |
| Controls whether differences in whitespace should be ignored or not. |
| + |
| ** `None`: |
| + |
| All differences in whitespace are highlighted. |
| + |
| ** `At Line End`: |
| + |
| Whitespace differences at the end of lines are ignored. |
| + |
| ** `Leading, At Line End`: |
| + |
| 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 a vertical dashed line |
| is displayed so that one can easily detect lines the exceed the |
| preferred line length. |
| + |
| image::images/user-review-ui-side-by-side-diff-screen-column.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-column.png"] |
| |
| - [[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"] |
| |
| - [[intraline-difference]]`Intraline Difference`: |
| + |
| Controls whether intraline differences should be highlighted. |
| + |
| image::images/user-review-ui-side-by-side-diff-screen-intraline-difference.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-intraline-difference.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. The language can also be set manually by selecting |
| it from the `Language` drop-down list. |
| + |
| image::images/user-review-ui-side-by-side-diff-screen-syntax-coloring.png[width=800, link="images/user-review-ui-side-by-side-diff-screen-syntax-coloring.png"] |
| |
| - [[whitespace-errors]]`Whitespace Errors`: |
| + |
| Controls whether whitespace errors are highlighted. |
| |
| - [[show-tabs]]`Show Tabs`: |
| + |
| Controls whether tabs are highlighted. |
| |
| - [[line-numbers]]`Line Numbers`: |
| + |
| Controls whether line numbers are shown. |
| |
| - [[empty-pane]]`Empty Pane`: |
| + |
| Controls whether empty panes are shown or not. The Left pane is empty when a |
| file was added; the right pane is empty when a file was deleted. |
| |
| - [[left-side]]`Left Side`: |
| + |
| Controls whether the left side is shown. This preference is not |
| persistent and is ignored by the `Save` button. Every time a |
| patch diff is opened, this preference is reset to `Show`. |
| |
| - [[top-menu]]`Top Menu`: |
| + |
| Controls whether the top menu is shown. |
| |
| - [[auto-hide-diff-table-header]]`Auto Hide Diff Table Header`: |
| + |
| Controls whether the diff table header should be automatically hidden |
| when scrolling down more than half of a page. |
| |
| - [[mark-reviewed]]`Mark Reviewed`: |
| + |
| Controls whether the files of the patch set should be automatically |
| marked as reviewed when they are viewed. |
| |
| - [[expand-all-comments]]`Expand All Comments`: |
| + |
| Controls whether all comments should be automatically expanded. |
| |
| - [[render]]`Render`: |
| + |
| Controls how patch files that exceed the screen size are rendered. |
| + |
| If `Fast` is selected file contents which are outside of the visible |
| area are not attached to the browser's DOM tree. This makes the |
| rendering fast, but searching by `Ctrl+F` only finds content which is |
| in the visible area. |
| + |
| If `Slow` is selected all file contents are attached to the browser's |
| DOM tree, which makes the rendering slow for large files. The advantage |
| of this setting is that `Ctrl+F` can be used to search in the complete |
| file. |
| + |
| Large files that exceed 4000 lines will not be fully rendered. |
| |
| [[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: |
| |
| - Change Screen |
| + |
| image::images/user-review-ui-change-screen-keyboard-shortcuts.png[width=800, link="images/user-review-ui-change-screen-keyboard-shortcuts.png"] |
| |
| - Side-by-Side Diff Screen |
| + |
| image::images/user-review-ui-side-by-side-diff-screen-keyboard-shortcuts.png[width=800, link="images/user-review-ui-side-by-side-diff-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. |
| |
| [[new-vs-old]] |
| == New Review UI vs. Old Review UI |
| |
| There are some important conceptual differences between the old and |
| new review UIs: |
| |
| - The old change screen directly shows all patch sets of the change. |
| With the new change screen only a single patch set is displayed; |
| users can switch between the patch sets by choosing another patch |
| set from the link:#patch-sets[Patch Sets] drop down panel in the |
| screen header. |
| - On the old side-by-side diff screen, new comments are inserted by |
| double-clicking on a line. With the new side-by-side diff screen |
| double-click is used to select a word for commenting on it; there |
| are link:#add-inline-comment[several ways to insert new comments], |
| e.g. by selecting a code block and clicking on the popup comment |
| icon. |
| |
| [[limitations]] |
| Limitations of the new review UI: |
| |
| - The new side-by-side diff screen cannot render images. |
| |
| - The new side-by-side diff screen isn't able to highlight line |
| endings. |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |