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 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.  Administrators can activate
 it system-wide by changing the link:config-gerrit.html[gerrit.changeScreen]
 setting to `CHANGE_SCREEN2`.

 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.

 By setting "Default", users can select to use whichever screen the site
 administrator has configured.

 [[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]
	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. Administrators can activate
	it system-wide by changing the link:config-gerrit.html[gerrit.changeScreen]
	setting to `CHANGE_SCREEN2`.

	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.

	By setting "Default", users can select to use whichever screen the site
	administrator has configured.

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