Documentation/intro-change-screen.txt - gerrit - Git at Google

 = 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 or
 HTML fragments 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 switch between the old and new screens by selecting "Old Screen" or
 "New Screen" in the "Change View" setting 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 commands to checkout, pull, or cherry-pick a patchset 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:

 * j / k: next line / previous line
 * 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)
 * / or <Ctrl> + f: 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

 Reviewers who actually voted on the change or were added to the change but didn't
 vote yet are shown as "chip" in the 'Reviewers' field.

 The votes per category are listed above the File list.

 To add a reviewer, use the 'Add...' button to the right of the 'Reviewers'
 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".

 Votable categories are shown as a tooltip for each reviewer.

 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 changes on which the current change depends (ancestors) and
 open changes that depend on the current change (descendants). 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".

 Unlike the old change screen it doesn't explicitly say "needed by" and "depends
 on" any more, but the relationship can still be inferred from the position of
 the change in the list.  Changes listed above the current change are dependents;
 changes below the current change are dependencies.

 Indicators are appended on the commit message headlines of related changes to
 signify dependencies on outdated changes, or commits that are not associated to
 changes under review:

 If the selected patch set of a change is older than its latest patch set,
 the change is marked with an orange dot.

 If a descendant change depends on a patch set that is older than the selected
 patch set of a change, the descendent change is marked with a tilde (~).

 If an ancestor commit is not associated to a Gerrit change, i.e. has been pushed
 directly to the repository bypassing review, it is marked with a black dot.

 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
 ---------
	= 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 or
	HTML fragments 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 switch between the old and new screens by selecting "Old Screen" or
	"New Screen" in the "Change View" setting 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 commands to checkout, pull, or cherry-pick a patchset 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:

	* j / k: next line / previous line
	* 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)
	* / or <Ctrl> + f: 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

	Reviewers who actually voted on the change or were added to the change but didn't
	vote yet are shown as "chip" in the 'Reviewers' field.

	The votes per category are listed above the File list.

	To add a reviewer, use the 'Add...' button to the right of the 'Reviewers'
	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".

	Votable categories are shown as a tooltip for each reviewer.

	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 changes on which the current change depends (ancestors) and
	open changes that depend on the current change (descendants). 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".

	Unlike the old change screen it doesn't explicitly say "needed by" and "depends
	on" any more, but the relationship can still be inferred from the position of
	the change in the list. Changes listed above the current change are dependents;
	changes below the current change are dependencies.

	Indicators are appended on the commit message headlines of related changes to
	signify dependencies on outdated changes, or commits that are not associated to
	changes under review:

	If the selected patch set of a change is older than its latest patch set,
	the change is marked with an orange dot.

	If a descendant change depends on a patch set that is older than the selected
	patch set of a change, the descendent change is marked with a tilde (~).

	If an ancestor commit is not associated to a Gerrit change, i.e. has been pushed
	directly to the repository bypassing review, it is marked with a black dot.

	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
	---------