ChangeScreen2: add documentation
Change-Id: Id2657f79ff2f64bd7cdd6c22828e0c428bec61ed
diff --git a/Documentation/index.txt b/Documentation/index.txt
index ee76855..438500f 100644
--- a/Documentation/index.txt
+++ b/Documentation/index.txt
@@ -8,6 +8,7 @@
.. link:licenses.html[Licenses and Notices]
. Installing
.. link:intro-quick.html[A Quick Introduction To Gerrit]
+.. link:intro-change-screen.html[A Quick Introduction To New Change Screen]
.. link:install.html[Installation Guide]
. Tutorial
.. Get started
diff --git a/Documentation/intro-change-screen.txt b/Documentation/intro-change-screen.txt
new file mode 100644
index 0000000..9a1ed0d
--- /dev/null
+++ b/Documentation/intro-change-screen.txt
@@ -0,0 +1,189 @@
+Change Screen - Introduction
+============================
+
+As of Gerrit 2.8 the change screen was redesigned from ground up. The old
+changes screen is deprecated and is going to 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 the facelift. The main highlights are under the hood:
+
+* Old style RPC was replaced by REST API
+* 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 action to
+the UI from a plugin.
+
+This document intended to help to switch to the new change screen.
+Further information on the topic can be found here:
+link:https://groups.google.com/forum/#!topic/repo-discuss/6Ryz9p6AzgE[CS2 thread on the ML]
+
+[[configuration]]
+Configuration
+~~~~~~~~~~~~~
+
+At the time of this writing the new change screen is deactivated by default.
+There are system wide and user preference options to activate it:
+link:config-gerrit.html[gerrit.changeScreen]. If `gerrit.changeScreen` is set
+to `CHANGE_SCREEN2` then the new change screen is activated. User can
+deactivate it by setting `OLD_UI` on user preference site. And the other way
+around.
+
+[[switching-between-patch-sets]]
+Switching between patch sets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As already mentioned above, the main diference between the old and the new
+change sreen is the fact, that only one patch set is presented on the
+screen. To switch to other patch sets for the given change drop down
+Revisions box is used on the right upper side of the change header.
+Patch sets are always sorted in descending order. The known option to switch
+between ascending and reverse patch set srorting order is not supported any
+more on the new change screen.
+
+[[download-commands]]
+Download commands
+~~~~~~~~~~~~~~~~~
+
+The download commands moved to the Download drop down box. Patch file can be
+downloaded as base64 encoded or zipped version. There are pending patches to
+move download commands to core plugin to make it easy customizable.
+
+[[quick-approve]]
+Quick approve
+~~~~~~~~~~~~~
+
+The so called "Quick approve" button is some times confusing.
+Normal users (not maintainer) are seeing this as "Verified+1" button right to
+the "Reply" button. But 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 does "Code-Review+2" the button displays as Verified+1. If a
+verifier does "Verified+1" the button says "Code-Review+2". Important to note,
+that it is not possible per design to provide a comment when using this
+button, hence the name Quick approve. To provide comments, "Reply" button
+should be used.
+
+[[reply button]]
+Reply button
+~~~~~~~~~~~~
+
+This button correspond to the "Review" button on patch set panel on old change
+screen. The only new feature: the user can optionaly send email during the
+vote. Key bindings: "a" to open the drop down. "ESC" to close it.
+
+
+[[edit-commit-message]]
+Edit commit message
+~~~~~~~~~~~~~~~~~~~
+
+To edit commit message use "Edit Message" drop down box. It can be activated
+by clicking on "Edit Message" button on change header. Key bindings: "e" to
+open the drop down. "ESC" to close it.
+
+[[edit-change-topic]]
+Edit change topic
+~~~~~~~~~~~~~~~~~
+
+To edit the topic use edit icon right to 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 is appears and 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 appears
+on action panel: "Publish", "Delete Revision", "Delete Change". In Revisions
+drop down "(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 revision list. In addition red "draft" prefix appears on
+the file table.
+
+[[codemirror]]
+Codemirror
+~~~~~~~~~~
+
+On user preference "Side By Side and "Unified Diff" view can be configured.
+Use / key to start the CodeMirror search, like in vim. Key binding are not
+customizable at the moment. This can be changed in the future.
++
+Range comments are supported on Codemirror "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
+~~~~~~~~~
+
+Reviewers information is splitted into three different sections: Reviewers,
+who actually voted on the change (field "Reviewers"). Reviewer, who were added
+to the change but didn't vote yet (field "CC") and the actually votes per
+category (above "File" list).
++
+To add a reviewers, use "[+]" button right to the "CC" field. Typing into
+suggest oracle field activate the auto completion of reviewers user or groups.
++
+To remove reviewers click on the 'x' icon in reviewer's "chip".
++
+Use "c" key binding to add a reviewers. "ESC" to close the drop down.
+
+[[auto-refresh]]
+Auto refresh of change data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With new change screen polling for updates to the currently open change is
+activated per default. Default delay is 30 sec. For example, if other user
+votes or comments on the same change, then a popup window appears on the right
+bottom corner and user is notified that the change was updated. The delay is
+controlled by link:config-gerrit.html[change.updateDelay] configuration option.
+
+[[depends-on-needed-by]]
+"Depends on" and "Needed by"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Dependencies and dependents changes are put together on the change screen. It
+can be found on the "Related Changes" section (third main column). Key
+bindings: use "J" & "K" to navigate between the related changes or use "O" to
+open currently selected related change.
+
+[[file-table]]
+File table
+~~~~~~~~~~
+
+One difference between old and new change screen ist the fact, that the
+user can manually now toggle the "reviewed" flag. Use check box left to the
+line. Key bindings: "j" & "k" to navigate in the table.
+
+[[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 "Included In" button on the change header, left
+to the "Revisions" button. Note: this button is only visible, if the change is
+merged.
+
+[[missing-features]]
+Feature omitted for now
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* Permalink a change
+* Allow to see if a reviewer can't vote on a label
+* Allow to select a reference version as base for the comparison
