321 lines
11 KiB
Plaintext
321 lines
11 KiB
Plaintext
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 activated by default. It can be deactivated
|
|
system-wide by changing the link:config-gerrit.html[gerrit.changeScreen]
|
|
setting to `OLD_UI`. 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 'Patch Sets'
|
|
box is used on the right upper side of the change header. The current selected
|
|
patch set and the number of patch sets are shown on the drop down in the form:
|
|
"currently active patch set/number of patch sets". To indicate that not the
|
|
current patch set is active, change header contains: "Not Current" headline
|
|
instead of the change status.
|
|
|
|
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.
|
|
|
|
Key bindings: "n" & "p" to navigate between the patch sets.
|
|
|
|
[[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. Download-plugin must
|
|
be installed to see the download actions. If download plugin is not installed,
|
|
only patch files hyperlinks are shown.
|
|
|
|
Change state is cached in browsers, and the change state includes the download
|
|
URLs. If the change is modified (e.g. add a message or change a label vote)
|
|
the cached state in the browser will be invalidated and the download commands
|
|
will update. Another option to invalidate the cache is to use "Ctrl+Shift+R".
|
|
|
|
[[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 user can optionally send an email during the vote. Inline
|
|
comments are displayed inside of the ReplyBox. Editing them inline in the
|
|
ReplyBox is currently not possible.
|
|
|
|
Hint: if "LGTM" (acronym for 'Looks Good To Me') is typed in the ReplyBox,
|
|
then the highest possible score for 'Code-Review' category for logged in user
|
|
is selected.
|
|
|
|
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 and unstar changes
|
|
-----------------------
|
|
|
|
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.
|
|
|
|
[[permalink-change]]
|
|
Permalink a change
|
|
------------------
|
|
|
|
Hyperlink "Change <change link>" is a control that serves for two purposes:
|
|
reload the change and permalink the change. To permalink,
|
|
Right mouse click -> Copy Link Address.
|
|
|
|
Key bindings: "R" to reload 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'. 'Delete Revision' button is only visible when there are at
|
|
least two (draft) revisions. In the 'Patch Set' 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 'Patch Sets' 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. It can also be used to select a
|
|
region on one line to emphasize what the comment is related to.
|
|
|
|
Key bindings:
|
|
|
|
* n / p: next diff chunk / previous diff chunk
|
|
* ] / [: next file / previous file
|
|
* u: up to change
|
|
* c: create a new inline comment (focus has to be in codemirror view)
|
|
* /: search in the current file
|
|
* <Shift> + o: expand or collapse all comments on current line
|
|
* <Enter> or o: expand or collapse comment
|
|
* <Esc> or Cancel: comment edit
|
|
* i: toggle intraline differences
|
|
* ,: Show diff preferences
|
|
* <Ctrl> + s: Save draft comment
|
|
|
|
[[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"
|
|
-----------------
|
|
|
|
A tab control on the third column shows the related changes. There are 4
|
|
different tabs:
|
|
|
|
* Related Changes
|
|
|
|
This tab page shows open changes on which the current change depends and open
|
|
changes that depend on the current change. For merge commits it shows also the
|
|
closed changes that are going to be merged into the destination branch by
|
|
accepting the merge commit. It is kind of a dependency too, but not in the
|
|
sense of "these changes have to be submitted in order to submit this
|
|
change".
|
|
|
|
This tab is only visible if related changes for the current active
|
|
change exist.
|
|
|
|
* Same Topic Changes
|
|
|
|
Changes that share the same topic are listed on this tab page. Only changes
|
|
in status opened are currently shown.
|
|
|
|
This tab is only visible if same topic changes for the current active
|
|
change exist.
|
|
|
|
* Cherry-Picks Changes
|
|
|
|
Changes with the same change id for the current project are listed on this
|
|
tab page. Note that also abandoned or merged changes can be shown. Currently
|
|
the status of the listed changes is not shown.
|
|
|
|
This tab is only visible if cherry-picked changes for the current active
|
|
change exist.
|
|
|
|
* Conflicts With Changes
|
|
|
|
Changes that are conflicting with the current change are listed on this
|
|
tab. Only the changes that are mergeable are currently shown. Non mergeable
|
|
changes are filtered out.
|
|
|
|
This tab is only visible if there are conflicting changes with the
|
|
current change.
|
|
|
|
Key bindings: "J" & "K" to navigate between the related changes. "O" to
|
|
open the currently selected change on one of the related changes tab page.
|
|
|
|
[[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, "r" to toggle the
|
|
'reviewed' flag, and "o" or "Enter" to open diff in codemirror or unified diff
|
|
view.
|
|
|
|
[[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.
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|
|
|
|
SEARCHBOX
|
|
---------
|