| Change Screen - Introduction |
| ============================ |
| |
| As of Gerrit 2.8 the change screen was redesigned from the ground up. The old |
| change screen is deprecated and will be discontinued in one of the next Gerrit |
| releases. |
| |
| The design spirit of the new change screen is simplicity: only one patch set is |
| presented on the screen. The list of related changes is always visible and |
| optional elements are moved to pop down boxes. |
| |
| This is not only a facelift. The main highlights are under the hood: |
| |
| * Old style RPC calls are replaced by the REST API |
| * The prettify syntax highlighting library was replaced by Codemirror |
| * Automatic refresh of open changes |
| * Support to download a patch direct in browser: no local repo is needed |
| * JS API integration: it was never so easy to add change/revision actions to |
| the UI from a plugin. |
| |
| This document is intended to help users to switch to the new change screen. |
| |
| Further information on the topic can be found in the: |
| link:https://groups.google.com/forum/#!topic/repo-discuss/6Ryz9p6AzgE[ |
| CodeScreen2 thread on the repo-discuss mailing list]. |
| |
| [[configuration]] |
| Configuration |
| ------------- |
| |
| The new change screen is deactivated by default. It can be activated system-wide |
| by changing the link:config-gerrit.html[gerrit.changeScreen] setting to |
| `CHANGE_SCREEN2`. Users can deactivate it by setting `OLD_UI` on their user |
| preferences page. |
| |
| [[switching-between-patch-sets]] |
| Switching between patch sets |
| ---------------------------- |
| |
| As already mentioned above, the main difference between the old and the new |
| change screen is the fact that only one patch set is presented on the screen. |
| |
| To switch to other patch sets for the given change, the drop down 'Revisions' |
| box is used on the right upper side of the change header. |
| |
| Patch sets are always sorted in descending order. The option to switch between |
| ascending and reverse patch set sorting order is not supported on the new change |
| screen. |
| |
| [[download-commands]] |
| Download commands |
| ----------------- |
| |
| The download commands are moved to the 'Download' drop down box. Patch files |
| can be downloaded as base64 encoded or zipped versions. |
| |
| [[included-in]] |
| Included in |
| ----------- |
| |
| To see the branches a specific change was merged into and the list of the tags |
| a change was tagged with, use the 'Included In' drop down on the change header, |
| to the left of the 'Revisions' drop down. |
| |
| Note that this list is only visible on merged changes. |
| |
| [[quick-approve]] |
| Quick approve |
| ------------- |
| |
| The so called 'Quick approve' button is some times confusing. Normal users (i.e. |
| non-maintainers) see this as 'Verified+1' button to the right of the 'Reply' |
| button. |
| |
| The button is not always "Verified+1". The button appears if a user has |
| permission to vote the max score in exactly one label that the rules have marked |
| as NEED. |
| |
| For a maintainer with both 'Verified+1' and 'Code-Review+2' powers the button |
| does not appear, as both categories are still marked NEED and the maintainer has |
| permission to use both. If another maintainer scores 'Code-Review+2', then the |
| button displays as 'Verified+1'. If a verifier scores 'Verified+1' the button |
| displays as 'Code-Review+2'. |
| |
| It is important to note that by design, the user cannot provide a comment when |
| using this button, hence the name 'Quick approve'. To provide comments, the |
| 'Reply' button should be used. |
| |
| [[reply-button]] |
| Reply button |
| ------------ |
| |
| This button corresponds to the 'Review' button the on patch set panel on the old |
| change screen. The only new feature: the user can optionally send an email |
| during the vote. |
| |
| Key bindings: "a" to open the drop down. "ESC" to close it. |
| |
| [[edit-commit-message]] |
| Edit commit message |
| ------------------- |
| |
| To edit the commit message use the 'Edit Message' button on the change header, |
| which will open a drop-down editor box. |
| |
| Key bindings: "e" to open the drop down. "ESC" to close it. |
| |
| [[star-change]] |
| |
| Star change icon allows to star the change, so that "starredby:self" query can |
| retrieve the starred changes later. If the change is already starred, then |
| clicking the icon again unstars the change. |
| |
| Key bindings: "s" to star/unstar the change. |
| |
| [[edit-change-topic]] |
| Edit change topic |
| ----------------- |
| |
| To edit the topic use the edit icon to the right of the topic field. |
| |
| Key bindings: "t" to open the drop down. "ESC" to close it. |
| |
| [[abandon-restore]] |
| Abandon or Restore changes |
| -------------------------- |
| |
| When a change is abandoned or restored, a panel appears and a comment message |
| can be provided. |
| |
| [[working-with-drafts]] |
| Working with draft changes and patch sets |
| ----------------------------------------- |
| |
| When a change or a patch set is a draft, then three additional buttons appear on |
| the action panel: 'Publish', 'Delete Revision', and 'Delete Change'. In the |
| 'Revisions' drop down a "(DRAFT)" suffix is added to the patch set number to |
| indicate that the patch set is a draft. |
| |
| [[draft-comments]] |
| Highlight draft comments |
| ------------------------ |
| |
| If a patch set has draft comments that weren't published yet, then that patch |
| set is marked on the list in the 'Revisions' drop down list. In addition a red |
| "draft" prefix appears on the filenames in the file table. |
| |
| [[codemirror]] |
| Codemirror |
| ---------- |
| |
| On the user preferences page, 'Side By Side' or 'Unified Diff' view can be |
| configured. Use the "/" key to start the CodeMirror search, like in vim. |
| |
| Key bindings are not customizable at the moment. They may be added in the future. |
| |
| Range comments are supported on Codemirror's 'Side By Side' screen. Highlight |
| lines with the mouse and then click the bottom-most line number to create a |
| range comment for the highlighted lines. |
| |
| [[reviewers]] |
| Reviewers |
| --------- |
| |
| Reviewer are split into two groups: Reviewers who actually voted on the change |
| in the 'Reviewers' field, and reviewers, who were added to the change but didn't |
| vote yet in the 'CC' field. |
| |
| The votes per category are listed above the File list. |
| |
| To add a reviewer, use the '[+]' button to the right of the 'CC' field. Typing |
| into the pop-up text field activates auto completion of user or group names. |
| |
| To remove reviewers click on the 'x' icon in the reviewer's "chip". |
| |
| Key bindings: "c" to add a reviewer. "ESC" to close the drop down. |
| |
| [[auto-refresh]] |
| Auto refresh of change data |
| --------------------------- |
| |
| On the new change screen polling for updates to the currently open change is |
| activated per default. For example, if another user votes or comments on the |
| same change, then a popup window appears on the bottom right corner of the |
| screen to notify the user that the change was updated. |
| |
| The default delay is 30 seconds. It can be configured with the |
| link:config-gerrit.html[change.updateDelay] setting. |
| |
| [[related-changes]] |
| Related changes |
| --------------- |
| |
| Dependencies and dependent changes are listed in the 'Related Changes' drop |
| down. |
| |
| Key bindings: "J" & "K" to navigate between the related changes. "O" to |
| open the currently selected related change. |
| |
| [[file-table]] |
| File table |
| ---------- |
| |
| The user can now manually toggle the 'reviewed' flag per file using the check |
| box to the left of the filename. |
| |
| Key bindings: "j" & "k" to navigate in the file table, and "r" to toggle the |
| 'reviewed' flag. |
| |
| [[diff-against]] |
| Diff against |
| ------------ |
| |
| In the 'Diff against' dropdown, base reference version can be selected. On |
| selecting an entry the file table list is reloaded and shows only the files |
| that were changed compared to this reference version. The selected revision |
| is passed to the side by side view, so that code mirror windows "remember" |
| the base reference version choice made on the change screen. |
| |
| [[history]] |
| History |
| ------- |
| |
| The history table shows change messages and inline file comments. Expand All and |
| Collapse All buttons show/hide the messages. |
| |
| Key bindings: "x" expands all messages, "z" collapses them again. |
| |
| [[missing-features]] |
| Missing features |
| ---------------- |
| |
| Several features have not been implemented yet: |
| |
| * Permalink a change |
| * Allow to see if a reviewer can't vote on a label |
| * Change diff view preferences |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |