| :linkattrs: |
| = Review UI |
| |
| Reviewing changes is an important task and the Gerrit Web UI provides |
| many functionalities to make the review process comfortable and |
| efficient. |
| |
| The UI has three different main views, |
| |
| ** The dashboard, which shows all changes that are relevant to you |
| ** The change screen, which shows the change with all its metadata |
| ** The diff view, which shows changes to a single file |
| |
| [[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"] |
| |
| 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=400, link="images/user-review-ui-change-screen-topleft.png"] |
| |
| [[change-status]] |
| The change status shows the state of the change: |
| |
| - [[active]]`Active`: |
| + |
| The change is under active review. |
| |
| - [[merge-conflict]]`Merge Conflict`: |
| + |
| The change can't be merged due to conflicts. |
| |
| - [[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. |
| |
| [[star]] |
| === Star Change |
| |
| Clicking the star icon marks the change as a favorite: 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. |
| |
| [[change-info]] |
| === Change metadata |
| |
| The change metadata block contains detailed information about the change |
| and offers actions on the change. |
| |
| - [[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 by clicking on the pencil icon. 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-info-reviewers.png[width=600, link="images/user-review-ui-change-screen-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. |
| + |
| 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. |
| |
| - [[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. |
| |
| - [[actions]]Actions: |
| + |
| Actions buttons are at the top, 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=600, link="images/user-review-ui-change-screen-change-info-actions.png"] |
| |
| - [[labels]]Labels & Votes: |
| + |
| Approving votes are colored green; negative votes are colored red. |
| + |
| image::images/user-review-ui-change-screen-change-info-labels.png[width=400, 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"] |
| |
| [[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. |
| |
| [[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. |
| |
| image::images/user-review-ui-change-screen-patch-sets.png[width=487, 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. |
| |
| 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 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. |
| + |
| 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 selected patch set of the change is outdated; it is not the current |
| patch set of the change. |
| + |
| 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. |
| |
| ** [[closed-ancestor]]Closed ancestor: |
| + |
| 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`. |
| |
| ** [[closed-ancestor-abandoned]]Abandoned: |
| + |
| Indicates an abandoned change. |
| |
| - [[conflicts-with]]`Conflicts With`: |
| + |
| 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. |
| + |
| 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 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. |
| |
| [[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/gwt-user-review-ui-change-screen-reply.png[width=800, link="images/gwt-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. Some basic markdown-like syntax is supported which renders |
| indented lines preformatted, lines starting with "- " or "* " as list |
| items, and lines starting with "> " as block quotes (also see replying to |
| link:#reply-to-message[messages] and link:#reply-inline-comment[inline comments]). |
| |
| 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/gwt-user-review-ui-change-screen-replying.png[width=800, link="images/gwt-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/gwt-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/gwt-user-review-ui-change-screen-history.png[width=800, link="images/gwt-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/gwt-user-review-ui-change-screen-reply-to-comment.png[width=800, link="images/gwt-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/gwt-user-review-ui-change-screen-inline-comments.png[width=800, link="images/gwt-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/gwt-user-review-ui-change-screen-change-update.png[width=800, link="images/gwt-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/gwt-user-review-ui-change-screen-plugin-extensions.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-project-and-file.png[width=800, link="images/gwt-user-review-ui-side-by-side-diff-screen-project-and-file.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/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-patch-sets.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-no-differences.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-rename.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-navigation.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-inline-comments.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-comment-box.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-comment-reply.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-comment-edit.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-replied-done.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-comment.png[width=800, link="images/gwt-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/gwt-user-review-ui-side-by-side-diff-screen-commented.png[width=800, link="images/gwt-user-review-ui-side-by-side-diff-screen-commented.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=800, link="images/gwt-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/gwt-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/gwt-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/gwt-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 |
| --------- |