Merge branch 'stable-2.12' into stable-2.13

* stable-2.12:
  Upgrade JGit to 4.5.5.201812240535-r

Change-Id: Ie163ef97fa2c3b12eef720774e7cf333e02e3a49
diff --git a/.bazelrc b/.bazelrc
new file mode 100644
index 0000000..00acd27
--- /dev/null
+++ b/.bazelrc
@@ -0,0 +1 @@
+build --strategy=Javac=worker
diff --git a/.buckconfig b/.buckconfig
index 51318f3..b347a96 100644
--- a/.buckconfig
+++ b/.buckconfig
@@ -1,15 +1,14 @@
 [alias]
   api = //:api
-  api_deploy = //tools/maven:api_deploy
-  api_install = //tools/maven:api_install
-  war_deploy = //tools/maven:war_deploy
-  war_install = //tools/maven:war_install
   chrome = //:chrome
   docs = //Documentation:searchfree
   firefox = //:firefox
   gerrit = //:gerrit
+  gwtgerrit = //:gwtgerrit
   headless = //:headless
+  polygerrit = //:polygerrit
   release = //:release
+  releasenotes = //ReleaseNotes:html
   safari = //:safari
   soyc = //gerrit-gwtui:ui_soyc
   soyc_r = //gerrit-gwtui:ui_soyc_r
@@ -19,11 +18,16 @@
   includes = //tools/default.defs
 
 [java]
-  src_roots = java, resources
+  jar_spool_mode = direct_to_jar
+  src_roots = java, resources, src
 
 [project]
-  ignore = .git
+  ignore = .git, eclipse-out, bazel-gerrit, bin
+  parallel_parsing = true
 
 [cache]
   mode = dir
   dir = ~/.gerritcodereview/buck-cache/locally-built-artifacts
+
+[test]
+  excluded_labels = manual
diff --git a/.buckversion b/.buckversion
index 9daac2c..f5fe016 100644
--- a/.buckversion
+++ b/.buckversion
@@ -1 +1 @@
-1b03b4313b91b634bd604fc3487a05f877e59dee
+e64a2e2ada022f81e42be750b774024469551398
diff --git a/.editorconfig b/.editorconfig
index 1f149cf..cb18523 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -9,3 +9,4 @@
 charset = utf-8
 indent_style = space
 indent_size = 2
+continuation_indent_size = 4
diff --git a/.gitignore b/.gitignore
index 32a1826..0fe7572 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,14 +7,22 @@
 /.settings/org.eclipse.ltk.core.refactoring.prefs
 /test_site
 /.idea
-/gerrit-parent.iml
+*.iml
+*.eml
 *.sublime-*
 /gerrit-package-plugins
+/.bazel_path
 /.buckconfig.local
 /.buckjavaargs
 /.buckd
+/bazel-bin
+/bazel-genfiles
+/bazel-gerrit
+/bazel-out
+/bazel-testlogs
 /buck-cache
 /buck-out
+/eclipse-out
 /extras
 /local.properties
 *.pyc
@@ -23,3 +31,6 @@
 *.swp
 *.asc
 /bin/
+*~
+.primary_build_tool
+.gwt_work_dir
diff --git a/.gitmodules b/.gitmodules
index d75c98c..6c4d53c 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,23 +1,34 @@
 [submodule "plugins/commit-message-length-validator"]
 	path = plugins/commit-message-length-validator
 	url = ../plugins/commit-message-length-validator
+	branch = .
 
 [submodule "plugins/cookbook-plugin"]
 	path = plugins/cookbook-plugin
 	url = ../plugins/cookbook-plugin
+	branch = .
 
 [submodule "plugins/download-commands"]
 	path = plugins/download-commands
 	url = ../plugins/download-commands
+	branch = .
+
+[submodule "plugins/hooks"]
+	path = plugins/hooks
+	url = ../plugins/hooks
+	branch = .
 
 [submodule "plugins/replication"]
 	path = plugins/replication
 	url = ../plugins/replication
+	branch = .
 
 [submodule "plugins/reviewnotes"]
 	path = plugins/reviewnotes
 	url = ../plugins/reviewnotes
+	branch = .
 
 [submodule "plugins/singleusergroup"]
 	path = plugins/singleusergroup
 	url = ../plugins/singleusergroup
+	branch = .
diff --git a/.mailmap b/.mailmap
index c8e2f82..598d52d 100644
--- a/.mailmap
+++ b/.mailmap
@@ -9,7 +9,8 @@
 David Ostrovsky <david@ostrovsky.org>                                                       <d.ostrovsky@gmx.de>
 Deniz Türkoglu <deniz@spotify.com>                                                          Deniz Türkoglu <deniz@spotify.com>
 Deniz Türkoglu <deniz@spotify.com>                                                          Deniz Turkoglu <deniz@spotify.com>
-Edwin Kempin <edwin.kempin@sap.com>                                                         Edwin Kempin <edwin.kempin@gmail.com>
+Edwin Kempin <ekempin@google.com>                                                           Edwin Kempin <edwin.kempin@gmail.com>
+Edwin Kempin <ekempin@google.com>                                                           Edwin Kempin <edwin.kempin@sap.com>
 Eryk Szymanski <eryksz@gmail.com>                                                           <eryksz@google.com>
 Fredrik Luthander <fredrik.luthander@sonymobile.com>                                        <fredrik@gandaraj.com>
 Fredrik Luthander <fredrik.luthander@sonymobile.com>                                        <fredrik.luthander@sonyericsson.com>
diff --git a/.settings/org.eclipse.jdt.core.prefs b/.settings/org.eclipse.jdt.core.prefs
index 8f5678f..828234b 100644
--- a/.settings/org.eclipse.jdt.core.prefs
+++ b/.settings/org.eclipse.jdt.core.prefs
@@ -46,7 +46,7 @@
 org.eclipse.jdt.core.compiler.problem.methodWithConstructorName=warning
 org.eclipse.jdt.core.compiler.problem.missingDefaultCase=ignore
 org.eclipse.jdt.core.compiler.problem.missingDeprecatedAnnotation=ignore
-org.eclipse.jdt.core.compiler.problem.missingEnumCaseDespiteDefault=disabled
+org.eclipse.jdt.core.compiler.problem.missingEnumCaseDespiteDefault=enabled
 org.eclipse.jdt.core.compiler.problem.missingHashCodeMethod=warning
 org.eclipse.jdt.core.compiler.problem.missingJavadocComments=ignore
 org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsOverriding=disabled
@@ -92,7 +92,7 @@
 org.eclipse.jdt.core.compiler.problem.unclosedCloseable=warning
 org.eclipse.jdt.core.compiler.problem.undocumentedEmptyBlock=ignore
 org.eclipse.jdt.core.compiler.problem.unhandledWarningToken=warning
-org.eclipse.jdt.core.compiler.problem.unnecessaryElse=ignore
+org.eclipse.jdt.core.compiler.problem.unnecessaryElse=warning
 org.eclipse.jdt.core.compiler.problem.unnecessaryTypeCheck=warning
 org.eclipse.jdt.core.compiler.problem.unqualifiedFieldAccess=ignore
 org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownException=warning
diff --git a/.watchmanconfig b/.watchmanconfig
index b1869ba..4467aec 100644
--- a/.watchmanconfig
+++ b/.watchmanconfig
@@ -1,6 +1,7 @@
 {
   "ignore_dirs": [
-    "buck-out"
+    "buck-out",
+    "eclipse-out"
   ],
   "ignore_vcs": [
     ".git"
diff --git a/BUCK b/BUCK
index c986874..9657ff3 100644
--- a/BUCK
+++ b/BUCK
@@ -1,10 +1,12 @@
 include_defs('//tools/build.defs')
 
 gerrit_war(name = 'gerrit')
-gerrit_war(name = 'headless', ui = None)
-gerrit_war(name = 'chrome',   ui = 'ui_chrome')
-gerrit_war(name = 'firefox',  ui = 'ui_firefox')
-gerrit_war(name = 'safari',   ui = 'ui_safari')
+gerrit_war(name = 'gwtgerrit',   ui = 'ui_dbg')
+gerrit_war(name = 'headless',    ui = None)
+gerrit_war(name = 'chrome',      ui = 'ui_chrome')
+gerrit_war(name = 'firefox',     ui = 'ui_firefox')
+gerrit_war(name = 'safari',      ui = 'ui_safari')
+gerrit_war(name = 'polygerrit',  ui = 'polygerrit')
 gerrit_war(name = 'withdocs', docs = True)
 gerrit_war(name = 'release',  ui = 'ui_optdbg_r', docs = True, context = ['//plugins:core'],  visibility = ['//tools/maven:'])
 
diff --git a/Documentation/BUCK b/Documentation/BUCK
index 126bf1f..48ca579 100644
--- a/Documentation/BUCK
+++ b/Documentation/BUCK
@@ -1,16 +1,20 @@
 include_defs('//Documentation/asciidoc.defs')
 include_defs('//Documentation/config.defs')
+include_defs('//Documentation/license.defs')
 include_defs('//tools/git.defs')
 
 DOC_DIR = 'Documentation'
-JSUI = '//gerrit-gwtui:ui_module'
-MAIN = '//gerrit-pgm:pgm'
+
+JSUI_JAVA_DEPS = ['//gerrit-gwtui:ui_module']
+JSUI_NON_JAVA_DEPS = ['//polygerrit-ui/app:polygerrit_ui']
+MAIN_JAVA_DEPS = ['//gerrit-pgm:pgm']
 SRCS = glob(['*.txt'], excludes = ['licenses.txt'])
 
+
 genasciidoc(
   name = 'html',
   out = 'html.zip',
-  docdir = DOC_DIR,
+  directory = DOC_DIR,
   srcs = SRCS + [':licenses.txt'],
   attributes = documentation_attributes(git_describe()),
   backend = 'html5',
@@ -20,7 +24,7 @@
 genasciidoc(
   name = 'searchfree',
   out = 'searchfree.zip',
-  docdir = DOC_DIR,
+  directory = DOC_DIR,
   srcs = SRCS + [':licenses.txt'],
   attributes = documentation_attributes(git_describe()),
   backend = 'html5',
@@ -28,31 +32,23 @@
   visibility = ['PUBLIC'],
 )
 
-genrule(
+genlicenses(
   name = 'licenses.txt',
-  cmd = '$(exe :gen_licenses) --asciidoc '
-    + '--classpath $(classpath %s) ' % MAIN
-    + '--classpath $(classpath %s) ' % JSUI
-    + MAIN + ' ' + JSUI + ' >$OUT',
+  opts = ['--asciidoc'],
+  java_deps = JSUI_JAVA_DEPS + MAIN_JAVA_DEPS,
+  non_java_deps = JSUI_NON_JAVA_DEPS,
   out = 'licenses.txt',
 )
 
 # Required by Google for gerrit-review.
-genrule(
+genlicenses(
   name = 'js_licenses.txt',
-  cmd = '$(exe :gen_licenses) --partial '
-    + '--classpath $(classpath %s) ' % JSUI
-    + JSUI + ' >$OUT',
+  opts = ['--partial'],
+  java_deps = JSUI_JAVA_DEPS,
+  non_java_deps = JSUI_NON_JAVA_DEPS,
   out = 'js_licenses.txt',
 )
 
-genrule(
-  name = 'doc.css',
-  srcs = ['doc.css.in'],
-  cmd = 'cp $SRCS $OUT',
-  out = 'doc.css',
-)
-
 python_binary(
   name = 'gen_licenses',
   main = 'gen_licenses.py',
@@ -61,6 +57,7 @@
 python_binary(
   name = 'replace_macros',
   main = 'replace_macros.py',
+  visibility = ['//ReleaseNotes:'],
 )
 
 genrule(
diff --git a/Documentation/access-control.txt b/Documentation/access-control.txt
index 0758c5c..2cc8c05 100644
--- a/Documentation/access-control.txt
+++ b/Documentation/access-control.txt
@@ -99,21 +99,14 @@
 [[administrators]]
 === Administrators
 
-This is the Gerrit "root" identity. The capability
-link:access-control.html#capability_administrateServer['Administrate Server']
-is assigned to this predefined group on Gerrit site creation.
+This is a predefined group, created on Gerrit site initialization, that
+has the capability link:access-control.html#capability_administrateServer[
+'Administrate Server'] assigned.
 
-Users in the 'Administrators' group can perform any action under
-the Admin menu, to any group or project, without further validation
-or any other access controls.  In most installations only those
-users who have direct filesystem and database access would be
-placed into this group.
-
-Membership in the 'Administrators' group does not imply any other
-access rights.  Administrators do not automatically get code review
-approval or submit rights in projects.  This is a feature designed
-to permit administrative users to otherwise access Gerrit as any
-other normal user would, without needing two different accounts.
+It is a normal Gerrit group without magic. This means if you remove
+the 'Administrate Server' capability from it, its members are no longer
+Gerrit administrators, despite the group name. The group may also be
+renamed.
 
 
 [[non-interactive_users]]
@@ -211,8 +204,8 @@
 Permissions can be set on a single reference name to match one
 branch (e.g. `refs/heads/master`), or on a reference namespace
 (e.g. `+refs/heads/*+`) to match any branch starting with that
-prefix. So a permission with `+refs/heads/*+` will match
-`refs/heads/master` and `refs/heads/experimental`, etc.
+prefix. So a permission with `+refs/heads/*+` will match all of
+`refs/heads/master`, `refs/heads/experimental`, `refs/heads/release/1.0` etc.
 
 Reference names can also be described with a regular expression
 by prefixing the reference name with `^`.  For example
@@ -222,13 +215,21 @@
 The link:http://www.brics.dk/automaton/[dk.brics.automaton library]
 is used for evaluation of regular expression access control
 rules. See the library documentation for details on this
-particular regular expression flavor.
+particular regular expression flavor. One quirk is that the
+shortest possible pattern expansion must be a valid ref name:
+thus `^refs/heads/.*/name` will fail because `refs/heads//name`
+is not a valid reference, but `^refs/heads/.+/name` will work.
 
-References can have the current user name automatically included,
-creating dynamic access controls that change to match the currently
-logged in user.  For example to provide a personal sandbox space
-to all developers, `+refs/heads/sandbox/${username}/*+` allowing
-the user 'joe' to use 'refs/heads/sandbox/joe/foo'.
+References can have the user name or the sharded account ID of the
+current user automatically included, creating dynamic access controls
+that change to match the currently logged in user.  For example to
+provide a personal sandbox space to all developers,
+`+refs/heads/sandbox/${username}/*+` allows the user 'joe' to use
+'refs/heads/sandbox/joe/foo'. The sharded account ID can be used to
+give users access to their user branch in the `All-Users` repository,
+for example `+refs/users/${shardeduserid}+` is resolved to
+'refs/users/23/1011123' if the account ID of the current user is
+`1011123`.
 
 When evaluating a reference-level access right, Gerrit will use
 the full set of access rights to determine if the user
@@ -420,10 +421,10 @@
 To block push permission to `+refs/drafts/*+` the following permission rule can
 be configured:
 
-====
+----
   [access "refs/drafts/*"]
     push = block group Anonymous Users
-====
+----
 
 
 [[access_categories]]
@@ -563,7 +564,6 @@
 new changes for code review, this depends on which namespace the
 permission is granted to.
 
-
 [[category_push_direct]]
 ==== Direct Push
 
@@ -611,6 +611,20 @@
 `+refs/for/refs/heads/*+` namespace.
 
 
+[[category_add_patch_set]]
+=== Add Patch Set
+
+This category controls which users are allowed to upload new patch sets to
+existing changes. Irrespective of this permission, change owners are always
+allowed to upload new patch sets for their changes. This permission needs to be
+set on `refs/for/*`.
+
+By default, this permission is granted to `Registered Users` on `refs/for/*`,
+allowing all registered users to upload a new patch set to any change. Revoking
+this permission (by granting it to no groups and setting the "Exclusive" flag)
+will prevent users from uploading a patch set to a change they do not own.
+
+
 [[category_push_merge]]
 === Push Merge Commits
 
@@ -636,15 +650,15 @@
 project's repository.  Typically this would be done with a command line
 such as:
 
-====
+----
   git push ssh://USER@HOST:PORT/PROJECT tag v1.0
-====
+----
 
 Or:
 
-====
+----
   git push https://HOST/PROJECT tag v1.0
-====
+----
 
 Tags must be annotated (created with `git tag -a`), should exist in
 the `refs/tags/` namespace, and should be new.
@@ -676,15 +690,15 @@
 project's repository.  Typically this would be done with a command
 line such as:
 
-====
+----
   git push ssh://USER@HOST:PORT/PROJECT tag v1.0
-====
+----
 
 Or:
 
-====
+----
   git push https://HOST/PROJECT tag v1.0
-====
+----
 
 Tags must be signed (created with `git tag -s`), should exist in the
 `refs/tags/` namespace, and should be new.
@@ -786,7 +800,9 @@
 === Submit (On Behalf Of)
 
 This category permits users who have also been granted the `Submit`
-permission to submit changes on behalf of another user.
+permission to submit changes on behalf of another user, by using the
+`on_behalf_of` field in link:rest-api-changes.html#submit-input[SubmitInput]
+when link:rest-api-changes.html#submit-change[submitting using the REST API].
 
 Note that this permission is named `submitAs` in the `project.config`
 file.
@@ -1066,10 +1082,10 @@
 '-2' and '+2', but keep their existing voting permissions for the '-1..+1'
 range intact we would define:
 
-====
+----
   [access "refs/heads/*"]
     label-Code-Review = block -2..+2 group X
-====
+----
 
 The interpretation of the 'min..max' range in case of a blocking rule is: block
 every vote from '-INFINITE..min' and 'max..INFINITE'. For the example above it
@@ -1080,16 +1096,17 @@
 When an access section of a project contains a 'BLOCK' and an 'ALLOW' rule for
 the same permission then this 'ALLOW' rule overrides the 'BLOCK' rule:
 
-====
+----
   [access "refs/heads/*"]
     push = block group X
     push = group Y
-====
+----
 
 In this case a user which is a member of the group 'Y' will still be allowed to
 push to 'refs/heads/*' even if it is a member of the group 'X'.
 
-NOTE: An 'ALLOW' rule overrides a 'BLOCK' rule only when both of them are
+[NOTE]
+An 'ALLOW' rule overrides a 'BLOCK' rule only when both of them are
 inside the same access section of the same project. An 'ALLOW' rule in a
 different access section of the same project or in any access section in an
 inheriting project cannot override a 'BLOCK' rule.
@@ -1105,22 +1122,22 @@
 reproducibility of a build must be guaranteed. To achieve that we block 'push'
 permission for the <<anonymous_users,'Anonymous Users'>> in "`All-Projects`":
 
-====
+----
   [access "refs/tags/*"]
     push = block group Anonymous Users
-====
+----
 
 By blocking the <<anonymous_users,'Anonymous Users'>> we effectively block
 everyone as everyone is a member of that group. Note that the permission to
 create a tag is still necessary. Assuming that only <<category_owner,project
 owners>> are allowed to create tags, we would extend the example above:
 
-====
+----
   [access "refs/tags/*"]
     push = block group Anonymous Users
     create = group Project Owners
     pushTag = group Project Owners
-====
+----
 
 
 ==== Let only a dedicated group vote in a special category
@@ -1133,11 +1150,11 @@
 in this category and, of course, allow 'Release Engineers' to vote in that
 category. In the "`All-Projects`" we define the following rules:
 
-====
+----
   [access "refs/heads/stable*"]
     label-Release-Process = block -1..+1 group Anonymous Users
     label-Release-Process = -1..+1 group Release Engineers
-====
+----
 
 [[global_capabilities]]
 == Global Capabilities
@@ -1170,10 +1187,19 @@
 === Administrate Server
 
 This is in effect the owner and administrator role of the Gerrit
-instance.  Any members of a group granted this capability will be
+instance. Any members of a group granted this capability will be
 able to grant any access right to any group. They will also have all
 capabilities granted to them automatically.
 
+In most installations only those users who have direct filesystem and
+database access should be granted this capability.
+
+This capability does not imply any other access rights. Users that have
+this capability do not automatically get code review approval or submit
+rights in projects. This is a feature designed to permit administrative
+users to otherwise access Gerrit as any other normal user would,
+without needing two different accounts.
+
 
 [[capability_batchChangesLimit]]
 === Batch Changes Limit
diff --git a/Documentation/asciidoc.defs b/Documentation/asciidoc.defs
index 2caf725..4b17071 100644
--- a/Documentation/asciidoc.defs
+++ b/Documentation/asciidoc.defs
@@ -35,7 +35,7 @@
   for attribute in attributes:
     asciidoc.extend(['-a', attribute])
   asciidoc.append('$SRCS')
-  newsrcs = [":doc.css"]
+  newsrcs = []
   for src in srcs:
     fn = src
     # We have two cases: regular source files and generated files.
@@ -52,15 +52,13 @@
 
     genrule(
       name = ex,
-      cmd = '$(exe :replace_macros) --suffix="%s"' % EXPN +
+      cmd = '$(exe //Documentation:replace_macros) --suffix="%s"' % EXPN +
         ' -s ' + passed_src + ' -o $OUT' +
         (' --searchbox' if searchbox else ' --no-searchbox'),
       srcs = srcs,
       out = ex,
     )
 
-    # The new AsciiDoctor requires both the css file and include files are under
-    # the same directory. Luckily Buck allows us to use :target as SRCS now.
     newsrcs.append(':%s' % ex)
 
   genrule(
@@ -74,41 +72,42 @@
 def genasciidoc(
     name,
     out,
-    docdir,
+    directory,
     srcs = [],
     attributes = [],
     backend = None,
     searchbox = True,
+    resources = True,
     visibility = []):
   SUFFIX = '_htmlonly'
 
   genasciidoc_htmlonly(
-    name = name + SUFFIX,
+    name = name + SUFFIX if resources else name,
     srcs = srcs,
     attributes = attributes,
     backend = backend,
     searchbox = searchbox,
-    out = name + SUFFIX + '.zip',
+    out = (name + SUFFIX + '.zip') if resources else (name + '.zip'),
   )
 
-  genrule(
-    name = name,
-    cmd = 'cd $TMP;' +
-      'mkdir -p %s/images;' % docdir +
-      'unzip -q $(location %s) -d %s/;'
-      % (':' + name + SUFFIX, docdir) +
-      'for s in $SRCS;do ln -s $s %s;done;' % docdir +
-      'mv %s/*.{jpg,png} %s/images;' % (docdir, docdir) +
-      'cp $(location %s) LICENSES.txt;' % ':licenses.txt' +
-      'zip -qr $OUT *',
-    srcs = glob([
-        'images/*.jpg',
-        'images/*.png',
-      ]) + [
-        ':doc.css',
-        '//gerrit-prettify:prettify.min.css',
-        '//gerrit-prettify:prettify.min.js',
-      ],
-    out = out,
-    visibility = visibility,
-  )
+  if resources:
+    genrule(
+      name = name,
+      cmd = 'cd $TMP;' +
+        'mkdir -p %s/images;' % directory +
+        'unzip -q $(location %s) -d %s/;'
+        % (':' + name + SUFFIX, directory) +
+        'for s in $SRCS;do ln -s $s %s/;done;' % directory +
+        'mv %s/*.{jpg,png} %s/images;' % (directory, directory) +
+        'cp $(location %s) LICENSES.txt;' % ':licenses.txt' +
+        'zip -qr $OUT *',
+      srcs = glob([
+          'images/*.jpg',
+          'images/*.png',
+        ]) + [
+          '//gerrit-prettify:prettify.min.css',
+          '//gerrit-prettify:prettify.min.js',
+        ],
+      out = out,
+      visibility = visibility,
+    )
diff --git a/Documentation/cmd-apropos.txt b/Documentation/cmd-apropos.txt
index 8882af1..31d21c1 100644
--- a/Documentation/cmd-apropos.txt
+++ b/Documentation/cmd-apropos.txt
@@ -4,8 +4,9 @@
 gerrit apropos - Search Gerrit documentation index
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit apropos'
+_ssh_ -p <port> <host> _gerrit apropos_
   <query>
 --
 
@@ -19,12 +20,14 @@
 == SCRIPTING
 This command is intended to be used in scripts.
 
-Note: this feature is only available if documentation index was built.
+[NOTE]
+This feature is only available if documentation index was built.
 
 == EXAMPLES
 
-=====
+----
 $ ssh -p 29418 review.example.com gerrit apropos capabilities
+
     Gerrit Code Review - /config/ REST API:
     http://localhost:8080/Documentation/rest-api-config.html
 
@@ -45,7 +48,7 @@
 
     Gerrit Code Review - /access/ REST API:
     http://localhost:8080/Documentation/rest-api-access.html
-=====
+----
 
 == SEE ALSO
 
diff --git a/Documentation/cmd-ban-commit.txt b/Documentation/cmd-ban-commit.txt
index d5c09af..80f41f0 100644
--- a/Documentation/cmd-ban-commit.txt
+++ b/Documentation/cmd-ban-commit.txt
@@ -4,8 +4,9 @@
 gerrit ban-commit - Bans a commit from a project's repository.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit ban-commit'
+_ssh_ -p <port> <host> _gerrit ban-commit_
   [--reason <REASON>]
   <PROJECT>
   <COMMIT> ...
@@ -43,10 +44,10 @@
 Ban commit `421919d015c062fd28901fe144a78a555d0b5984` from project
 `myproject`:
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit ban-commit myproject \
 	421919d015c062fd28901fe144a78a555d0b5984
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-cherry-pick.txt b/Documentation/cmd-cherry-pick.txt
index 0c4cf91..de0b71b 100644
--- a/Documentation/cmd-cherry-pick.txt
+++ b/Documentation/cmd-cherry-pick.txt
@@ -4,10 +4,11 @@
 gerrit-cherry-pick - Download and cherry pick one or more changes
 
 == SYNOPSIS
+[verse]
 --
-'gerrit-cherry-pick' <remote> <changeid>...
-'gerrit-cherry-pick' --continue | --skip | --abort
-'gerrit-cherry-pick' --close <remote>
+_gerrit-cherry-pick_ <remote> <changeid>...
+_gerrit-cherry-pick_ --continue | --skip | --abort
+_gerrit-cherry-pick_ --close <remote>
 --
 
 == DESCRIPTION
@@ -32,11 +33,11 @@
 To obtain the 'gerrit-cherry-pick' script use scp, curl or wget to
 copy it to your local system:
 
-====
+----
   $ scp -p -P 29418 john.doe@review.example.com:bin/gerrit-cherry-pick ~/bin/
 
   $ curl -Lo ~/bin/gerrit-cherry-pick http://review.example.com/tools/bin/gerrit-cherry-pick
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-close-connection.txt b/Documentation/cmd-close-connection.txt
index 3314326..973441e 100644
--- a/Documentation/cmd-close-connection.txt
+++ b/Documentation/cmd-close-connection.txt
@@ -4,8 +4,9 @@
 gerrit close-connection - Close the specified SSH connection
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit close-connection' <SESSION_ID>
+_ssh_ -p <port> <host> _gerrit close-connection_ <SESSION_ID>
    [--wait]
 --
 
diff --git a/Documentation/cmd-create-account.txt b/Documentation/cmd-create-account.txt
index 2159e0e..62bd0aa 100644
--- a/Documentation/cmd-create-account.txt
+++ b/Documentation/cmd-create-account.txt
@@ -4,8 +4,9 @@
 gerrit create-account - Create a new user account.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit create-account'
+_ssh_ -p <port> <host> _gerrit create-account_
   [--group <GROUP>]
   [--full-name <FULLNAME>]
   [--email <EMAIL>]
@@ -67,9 +68,9 @@
 Create a new batch/role access user account called `watcher` in
 the 'Non-Interactive Users' group.
 
-====
+----
 	$ cat ~/.ssh/id_watcher.pub | ssh -p 29418 review.example.com gerrit create-account --group "'Non-Interactive Users'" --ssh-key - watcher
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-create-branch.txt b/Documentation/cmd-create-branch.txt
index 671adfe..336af56d 100644
--- a/Documentation/cmd-create-branch.txt
+++ b/Documentation/cmd-create-branch.txt
@@ -4,8 +4,9 @@
 gerrit create-branch - Create a new branch
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit create-branch'
+_ssh_ -p <port> <host> _gerrit create-branch_
   <PROJECT>
   <NAME>
   <REVISION>
@@ -38,9 +39,9 @@
 Create a new branch called 'newbranch' from the 'master' branch of
 the project 'myproject'.
 
-====
+----
     $ ssh -p 29418 review.example.com gerrit create-branch myproject newbranch master
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-create-group.txt b/Documentation/cmd-create-group.txt
index d02e2ea..7f1f463 100644
--- a/Documentation/cmd-create-group.txt
+++ b/Documentation/cmd-create-group.txt
@@ -4,8 +4,9 @@
 gerrit create-group - Create a new account group.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit create-group'
+_ssh_ -p <port> <host> _gerrit create-group_
   [--owner <GROUP> | -o <GROUP>]
   [--description <DESC> | -d <DESC>]
   [--member <USERNAME>]
@@ -66,16 +67,16 @@
 Create a new account group called `gerritdev` with two initial members
 `developer1` and `developer2`.  The group should be owned by itself:
 
-====
+----
 	$ ssh -p 29418 user@review.example.com gerrit create-group --member developer1 --member developer2 gerritdev
-====
+----
 
 Create a new account group called `Foo` owned by the `Foo-admin` group.
 Put `developer1` as the initial member and include group description:
 
-====
+----
 	$ ssh -p 29418 user@review.example.com gerrit create-group --owner Foo-admin --member developer1 --description "'Foo description'" Foo
-====
+----
 
 Note that it is necessary to quote the description twice.  The local
 shell needs double quotes around the value to ensure the single quotes
diff --git a/Documentation/cmd-create-project.txt b/Documentation/cmd-create-project.txt
index d1108b5..503bd12 100644
--- a/Documentation/cmd-create-project.txt
+++ b/Documentation/cmd-create-project.txt
@@ -4,8 +4,9 @@
 gerrit create-project - Create a new hosted project
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit create-project'
+_ssh_ -p <port> <host> _gerrit create-project_
   [--owner <GROUP> ... | -o <GROUP> ...]
   [--parent <NAME> | -p <NAME> ]
   [--suggest-parents | -S ]
@@ -170,15 +171,15 @@
 == EXAMPLES
 Create a new project called `tools/gerrit`:
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit create-project tools/gerrit.git
-====
+----
 
 Create a new project with a description:
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit create-project tool.git --description "'Tools used by build system'"
-====
+----
 
 Note that it is necessary to quote the description twice.  The local
 shell needs double quotes around the value to ensure the single quotes
@@ -189,9 +190,9 @@
 If the replication plugin is installed, the plugin will attempt to
 perform remote repository creation by a Bourne shell script:
 
-====
+----
   mkdir -p '/base/project.git' && cd '/base/project.git' && git init --bare && git update-ref HEAD refs/heads/master
-====
+----
 
 For this to work successfully the remote system must be able to run
 arbitrary shell scripts, and must have `git` in the user's PATH
diff --git a/Documentation/cmd-flush-caches.txt b/Documentation/cmd-flush-caches.txt
index aa9790d..4716f3b 100644
--- a/Documentation/cmd-flush-caches.txt
+++ b/Documentation/cmd-flush-caches.txt
@@ -4,10 +4,11 @@
 gerrit flush-caches - Flush some/all server caches from memory
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit flush-caches' --all
-'ssh' -p <port> <host> 'gerrit flush-caches' --list
-'ssh' -p <port> <host> 'gerrit flush-caches' --cache <NAME> ...
+_ssh_ -p <port> <host> _gerrit flush-caches_ --all
+_ssh_ -p <port> <host> _gerrit flush-caches_ --list
+_ssh_ -p <port> <host> _gerrit flush-caches_ --cache <NAME> ...
 --
 
 == DESCRIPTION
@@ -56,7 +57,7 @@
 == EXAMPLES
 List caches available for flushing:
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit flush-caches --list
 	accounts
 	accounts_byemail
@@ -67,32 +68,32 @@
 	projects
 	sshkeys
 	web_sessions
-====
+----
 
 Flush all caches known to the server, forcing them to recompute:
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit flush-caches --all
-====
+----
 
 or
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit flush-caches
-====
+----
 
 Flush only the "sshkeys" cache, after manually editing an SSH key
 for a user:
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit flush-caches --cache sshkeys
-====
+----
 
 Flush "web_sessions", forcing all users to sign-in again:
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit flush-caches --cache web_sessions
-====
+----
 
 == SEE ALSO
 
diff --git a/Documentation/cmd-gc.txt b/Documentation/cmd-gc.txt
index b7388a1..1d1cc00 100644
--- a/Documentation/cmd-gc.txt
+++ b/Documentation/cmd-gc.txt
@@ -4,8 +4,9 @@
 gerrit gc - Run the Git garbage collection
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit gc'
+_ssh_ -p <port> <host> _gerrit gc_
   [--all]
   [--show-progress]
   [--aggressive]
@@ -52,7 +53,7 @@
 
 Run the Git garbage collection for the projects 'myProject' and
 'yourProject':
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit gc myProject yourProject
 	collecting garbage for "myProject":
 	...
@@ -61,12 +62,12 @@
 	collecting garbage for "yourProject":
 	...
 	done.
-=====
+----
 
 Run the Git garbage collection for all projects:
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit gc --all
-=====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-gsql.txt b/Documentation/cmd-gsql.txt
index 411eb00..d2eb783 100644
--- a/Documentation/cmd-gsql.txt
+++ b/Documentation/cmd-gsql.txt
@@ -4,8 +4,9 @@
 gerrit gsql - Administrative interface to active database
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit gsql'
+_ssh_ -p <port> <host> _gerrit gsql_
   [--format {PRETTY | JSON | JSON_SINGLE}]
   [-c QUERY]
 --
@@ -40,7 +41,7 @@
 == EXAMPLES
 To manually correct a user's SSH user name:
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit gsql
 	Welcome to Gerrit Code Review v2.0.25
 	(PostgreSQL 8.3.8)
@@ -53,7 +54,7 @@
 	Bye
 
 	$ ssh -p 29418 review.example.com gerrit flush-caches --cache sshkeys --cache accounts
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-hook-commit-msg.txt b/Documentation/cmd-hook-commit-msg.txt
index e102186..ffdd5da 100644
--- a/Documentation/cmd-hook-commit-msg.txt
+++ b/Documentation/cmd-hook-commit-msg.txt
@@ -63,26 +63,26 @@
 
 You can use either of the below commands:
 
-====
+----
   $ scp -p -P 29418 <your username>@<your Gerrit review server>:hooks/commit-msg <local path to your git>/.git/hooks/
 
   $ curl -Lo <local path to your git>/.git/hooks/commit-msg <your Gerrit http URL>/tools/hooks/commit-msg
-====
+----
 
 A specific example of this might look something like this:
 
 .Example
-====
+----
   $ scp -p -P 29418 john.doe@review.example.com:hooks/commit-msg ~/duhproject/.git/hooks/
 
   $ curl -Lo ~/duhproject/.git/hooks/commit-msg http://review.example.com/tools/hooks/commit-msg
-====
+----
 
 Make sure the hook file is executable:
 
-====
+----
   $ chmod u+x ~/duhproject/.git/hooks/commit-msg
-====
+----
 
 == SEE ALSO
 
diff --git a/Documentation/cmd-index-activate.txt b/Documentation/cmd-index-activate.txt
index aafbd19..418e872 100644
--- a/Documentation/cmd-index-activate.txt
+++ b/Documentation/cmd-index-activate.txt
@@ -4,8 +4,9 @@
 gerrit index activate - Activate the latest index version available
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit index activate'
+_ssh_ -p <port> <host> _gerrit index activate <INDEX>_
 --
 
 == DESCRIPTION
@@ -24,6 +25,20 @@
 == SCRIPTING
 This command is intended to be used in scripts.
 
+== OPTIONS
+<INDEX>::
+  The index to activate.
+  Currently supported values:
+    * changes
+    * accounts
+
+== EXAMPLES
+Activate the latest change index:
+
+----
+  $ ssh -p 29418 review.example.com gerrit activate changes
+----
+
 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/cmd-index-changes.txt b/Documentation/cmd-index-changes.txt
new file mode 100644
index 0000000..d38c51a
--- /dev/null
+++ b/Documentation/cmd-index-changes.txt
@@ -0,0 +1,41 @@
+= gerrit index changes
+
+== NAME
+gerrit index changes - Index one or more changes.
+
+== SYNOPSIS
+[verse]
+--
+_ssh_ -p <port> <host> _gerrit index changes_ <CHANGE> [<CHANGE> ...]
+--
+
+== DESCRIPTION
+Indexes one or more changes.
+
+Changes can be specified in the link:rest-api-changes.html#change-id[same format]
+supported by the REST API.
+
+== ACCESS
+Caller must have the 'Maintain Server' capability, or be the owner of the change
+to be indexed.
+
+== SCRIPTING
+This command is intended to be used in scripts.
+
+== OPTIONS
+--CHANGE::
+    Required; changes to be indexed.
+
+== EXAMPLES
+Index changes with legacy ID numbers 1 and 2.
+
+----
+    $ ssh -p 29418 user@review.example.com gerrit index changes 1 2
+----
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------
diff --git a/Documentation/cmd-index-start.txt b/Documentation/cmd-index-start.txt
index 1e4b24b..fbe4f3f 100644
--- a/Documentation/cmd-index-start.txt
+++ b/Documentation/cmd-index-start.txt
@@ -4,8 +4,9 @@
 gerrit index start - Start the online indexer
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit index start'
+_ssh_ -p <port> <host> _gerrit index start_ <INDEX> [--force]
 --
 
 == DESCRIPTION
@@ -25,6 +26,23 @@
 == SCRIPTING
 This command is intended to be used in scripts.
 
+== OPTIONS
+<INDEX>::
+  Restart the online indexer on this secondary index.
+  Currently supported values:
+    * changes
+    * accounts
+
+--force::
+  Force an online re-index.
+
+== EXAMPLES
+Start the online indexer for the 'changes' index:
+
+----
+  $ ssh -p 29418 review.example.com gerrit index start changes
+----
+
 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/cmd-index.txt b/Documentation/cmd-index.txt
index 90212fb..7af65ce 100644
--- a/Documentation/cmd-index.txt
+++ b/Documentation/cmd-index.txt
@@ -7,11 +7,13 @@
 
 To download a client command or hook, use scp or an http client:
 
+----
   $ scp -p -P 29418 john.doe@review.example.com:bin/gerrit-cherry-pick ~/bin/
   $ scp -p -P 29418 john.doe@review.example.com:hooks/commit-msg .git/hooks/
 
   $ curl -Lo ~/bin/gerrit-cherry-pick http://review.example.com/tools/bin/gerrit-cherry-pick
   $ curl -Lo .git/hooks/commit-msg http://review.example.com/tools/hooks/commit-msg
+----
 
 For more details on how to determine the correct SSH port number,
 see link:user-upload.html#test_ssh[Testing Your SSH Connection].
@@ -38,7 +40,9 @@
 not provide an interactive shell, the commands must be triggered
 from an ssh client, for example:
 
+----
   $ ssh -p 29418 review.example.com gerrit ls-projects
+----
 
 For more details on how to determine the correct SSH port number,
 see link:user-upload.html#test_ssh[Testing Your SSH Connection].
@@ -78,6 +82,9 @@
 link:cmd-set-head.html[gerrit set-head]::
 	Change the HEAD reference of a project.
 
+link:cmd-set-project.html[gerrit set-project]::
+	Change a project's settings.
+
 link:cmd-set-reviewers.html[gerrit set-reviewers]::
 	Add or remove reviewers on a change.
 
@@ -126,6 +133,9 @@
 link:cmd-index-start.html[gerrit index start]::
 	Start the online indexer.
 
+link:cmd-index-changes.html[gerrit index changes]::
+	Index one or more changes.
+
 link:cmd-logging-ls-level.html[gerrit logging ls-level]::
 	List loggers and their logging level.
 
@@ -162,9 +172,6 @@
 link:cmd-set-members.html[gerrit set-members]::
 	Set group members.
 
-link:cmd-set-project.html[gerrit set-project]::
-	Change a project's settings.
-
 link:cmd-set-project-parent.html[gerrit set-project-parent]::
 	Change the project permissions are inherited from.
 
diff --git a/Documentation/cmd-kill.txt b/Documentation/cmd-kill.txt
index c64c537..ac8e802 100644
--- a/Documentation/cmd-kill.txt
+++ b/Documentation/cmd-kill.txt
@@ -4,8 +4,9 @@
 kill - Cancel or abort a background task
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'kill' <ID> ...
+_ssh_ -p <port> <host> _kill_ <ID> ...
 --
 
 == DESCRIPTION
diff --git a/Documentation/cmd-logging-ls-level.txt b/Documentation/cmd-logging-ls-level.txt
index c59dc3f..ee015bb 100644
--- a/Documentation/cmd-logging-ls-level.txt
+++ b/Documentation/cmd-logging-ls-level.txt
@@ -6,8 +6,9 @@
 gerrit logging ls - view the logging level
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit logging ls-level | ls'
+_ssh_ -p <port> <host> _gerrit logging ls-level_ | _ls_
   <NAME>
 --
 
@@ -25,15 +26,15 @@
 == Examples
 
 View the logging level of the loggers in the package com.google:
-=====
+----
     $ssh -p 29418 review.example.com gerrit logging ls-level \
      com.google.
-=====
+----
 
 View the logging level of every logger
-=====
+----
     $ssh -p 29418 review.example.com gerrit logging ls-level
-=====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-logging-set-level.txt b/Documentation/cmd-logging-set-level.txt
index 38062cb..5baa968 100644
--- a/Documentation/cmd-logging-set-level.txt
+++ b/Documentation/cmd-logging-set-level.txt
@@ -6,8 +6,9 @@
 gerrit logging set - set the logging level
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit logging set-level | set'
+_ssh_ -p <port> <host> _gerrit logging set-level_ | _set_
   <LEVEL>
   <NAME>
 --
@@ -32,16 +33,16 @@
 == Examples
 
 Change the logging level of the loggers in the package com.google to DEBUG.
-=====
+----
     $ssh -p 29418 review.example.com gerrit logging set-level \
      debug com.google.
-=====
+----
 
 Reset the logging level of every logger to what they were at deployment time.
-=====
+----
     $ssh -p 29418 review.example.com gerrit logging set-level \
      reset
-=====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-ls-groups.txt b/Documentation/cmd-ls-groups.txt
index 651cebe..d8eef8b 100644
--- a/Documentation/cmd-ls-groups.txt
+++ b/Documentation/cmd-ls-groups.txt
@@ -4,8 +4,9 @@
 gerrit ls-groups - List groups visible to caller
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit ls-groups'
+_ssh_ -p <port> <host> _gerrit ls-groups_
   [--project <NAME> | -p <NAME>]
   [--user <NAME> | -u <NAME>]
   [--owned]
@@ -86,55 +87,55 @@
 == EXAMPLES
 
 List visible groups:
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit ls-groups
 	Administrators
 	Anonymous Users
 	MyProject_Committers
 	Project Owners
 	Registered Users
-=====
+----
 
 List all groups for which any permission is set for the project
 "MyProject":
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit ls-groups --project MyProject
 	MyProject_Committers
 	Project Owners
 	Registered Users
-=====
+----
 
 List all groups which are owned by the calling user:
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit ls-groups --owned
 	MyProject_Committers
 	MyProject_Verifiers
-=====
+----
 
 Check if the calling user owns the group `MyProject_Committers`. If
 `MyProject_Committers` is returned the calling user owns this group.
 If the result is empty, the calling user doesn't own the group.
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit ls-groups --owned -q MyProject_Committers
 	MyProject_Committers
-=====
+----
 
 Extract the UUID of the 'Administrators' group:
 
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit ls-groups -v | awk '-F\t' '$1 == "Administrators" {print $2}'
 	ad463411db3eec4e1efb0d73f55183c1db2fd82a
-=====
+----
 
 Extract and expand the multi-line description of the 'Administrators'
 group:
 
-=====
+----
 	$ printf "$(ssh -p 29418 review.example.com gerrit ls-groups -v | awk '-F\t' '$1 == "Administrators" {print $3}')\n"
 	This is a
 	multi-line
 	description.
-=====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-ls-members.txt b/Documentation/cmd-ls-members.txt
index f8708d3..a6d492c 100644
--- a/Documentation/cmd-ls-members.txt
+++ b/Documentation/cmd-ls-members.txt
@@ -4,8 +4,9 @@
 gerrit ls-members - Show members of a given group
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit ls-members GROUPNAME'
+_ssh_ -p <port> <host> _gerrit ls-members_ GROUPNAME
   [--recursive]
 --
 
@@ -38,19 +39,19 @@
 == EXAMPLES
 
 List members of the Administrators group:
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit ls-members Administrators
 	id      username  full name    email
 	100000  jim     Jim Bob somebody@example.com
 	100001  johnny  John Smith      n/a
 	100002  mrnoname        n/a     someoneelse@example.com
-=====
+----
 
 List members of a non-existent group:
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit ls-members BadlySpelledGroup
 	Group not found or not visible
-=====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-ls-projects.txt b/Documentation/cmd-ls-projects.txt
index 26b20a7..e2e71ff 100644
--- a/Documentation/cmd-ls-projects.txt
+++ b/Documentation/cmd-ls-projects.txt
@@ -4,8 +4,9 @@
 gerrit ls-projects - List projects visible to caller
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit ls-projects'
+_ssh_ -p <port> <host> _gerrit ls-projects_
   [--show-branch <BRANCH> ...]
   [--description | -d]
   [--tree | -t]
@@ -58,7 +59,7 @@
 
 --type::
 	Display only projects of the specified type.  If not
-	specified, defaults to `code`. Supported types:
+	specified, defaults to `all`. Supported types:
 +
 --
 `code`:: Any project likely to contain user files.
@@ -113,7 +114,7 @@
 == EXAMPLES
 
 List visible projects:
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit ls-projects
 	platform/manifest
 	tools/gerrit
@@ -127,16 +128,16 @@
 	$ curl http://review.example.com/projects/tools/
 	tools/gerrit
 	tools/gwtorm
-=====
+----
 
 Clone any project visible to the user:
-====
+----
 	for p in `ssh -p 29418 review.example.com gerrit ls-projects`
 	do
 	  mkdir -p `dirname "$p"`
 	  git clone --bare "ssh://review.example.com:29418/$p.git" "$p.git"
 	done
-====
+----
 
 == SEE ALSO
 
diff --git a/Documentation/cmd-ls-user-refs.txt b/Documentation/cmd-ls-user-refs.txt
index 11781de..1a87fc9 100644
--- a/Documentation/cmd-ls-user-refs.txt
+++ b/Documentation/cmd-ls-user-refs.txt
@@ -4,8 +4,9 @@
 gerrit ls-user-refs - List refs visible to a specific user
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit ls-user-refs'
+_ssh_ -p <port> <host> _gerrit ls-user-refs_
   [--project PROJECT> | -p <PROJECT>]
   [--user <USER> | -u <USER>]
   [--only-refs-heads]
@@ -40,9 +41,9 @@
 == EXAMPLES
 
 List visible refs for the user "mr.developer" in project "gerrit"
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit ls-user-refs -p gerrit -u mr.developer
-=====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-plugin-enable.txt b/Documentation/cmd-plugin-enable.txt
index c8022ef..9b52736 100644
--- a/Documentation/cmd-plugin-enable.txt
+++ b/Documentation/cmd-plugin-enable.txt
@@ -4,8 +4,9 @@
 plugin enable - Enable plugins.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit plugin enable'
+_ssh_ -p <port> <host> _gerrit plugin enable_
   <NAME> ...
 --
 
@@ -30,9 +31,9 @@
 == EXAMPLES
 Enable a plugin:
 
-====
+----
 	ssh -p 29418 localhost gerrit plugin enable my-plugin
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-plugin-install.txt b/Documentation/cmd-plugin-install.txt
index 0ce6d7d..5443613 100644
--- a/Documentation/cmd-plugin-install.txt
+++ b/Documentation/cmd-plugin-install.txt
@@ -6,8 +6,9 @@
 plugin add - Install/Add a plugin.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit plugin install | add'
+_ssh_ -p <port> <host> _gerrit plugin install_ | _add_
   [--name <NAME> | -n <NAME>]
   - | <URL> | <PATH>
 --
@@ -44,31 +45,31 @@
 == EXAMPLES
 Install a plugin from an absolute file path on the server's host:
 
-====
+----
 	ssh -p 29418 localhost gerrit plugin install -n name.jar \
 	  $(pwd)/my-plugin.jar
-====
+----
 
-Install a WebUi plugin from an absolute file path on the server's host:
+Install a WebUI plugin from an absolute file path on the server's host:
 
-====
+----
   ssh -p 29418 localhost gerrit plugin install -n name.js \
     $(pwd)/my-webui-plugin.js
-====
+----
 
 Install a plugin from an HTTP site:
 
-====
+----
 	ssh -p 29418 localhost gerrit plugin install -n name.jar \
 	  http://build-server/output/our-plugin
-====
+----
 
 Install a plugin from piped input:
 
-====
+----
 	ssh -p 29418 localhost gerrit plugin install -n name.jar \
 	  - <target/name-0.1.jar
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-plugin-ls.txt b/Documentation/cmd-plugin-ls.txt
index 234ce87..d329db5 100644
--- a/Documentation/cmd-plugin-ls.txt
+++ b/Documentation/cmd-plugin-ls.txt
@@ -4,8 +4,9 @@
 plugin ls - List the installed plugins.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit plugin ls'
+_ssh_ -p <port> <host> _gerrit plugin ls_
   [--all | -a]
   [--format {text | json | json_compact}]
 --
diff --git a/Documentation/cmd-plugin-reload.txt b/Documentation/cmd-plugin-reload.txt
index 88cb1f3..ad1e5e7 100644
--- a/Documentation/cmd-plugin-reload.txt
+++ b/Documentation/cmd-plugin-reload.txt
@@ -4,8 +4,9 @@
 plugin reload - Reload/Restart plugins.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit plugin reload'
+_ssh_ -p <port> <host> _gerrit plugin reload_
   <NAME> ...
 --
 
@@ -34,9 +35,9 @@
 == EXAMPLES
 Reload a plugin:
 
-====
+----
 	ssh -p 29418 localhost gerrit plugin reload my-plugin
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-plugin-remove.txt b/Documentation/cmd-plugin-remove.txt
index 770df85..805c7b4 100644
--- a/Documentation/cmd-plugin-remove.txt
+++ b/Documentation/cmd-plugin-remove.txt
@@ -6,8 +6,9 @@
 plugin rm - Disable plugins.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit plugin remove | rm'
+_ssh_ -p <port> <host> _gerrit plugin remove_ | _rm_
   <NAME> ...
 --
 
@@ -31,9 +32,9 @@
 == EXAMPLES
 Disable a plugin:
 
-====
+----
 	ssh -p 29418 localhost gerrit plugin remove my-plugin
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-query.txt b/Documentation/cmd-query.txt
index 090781b..1faf1b0 100644
--- a/Documentation/cmd-query.txt
+++ b/Documentation/cmd-query.txt
@@ -4,8 +4,9 @@
 gerrit query - Query the change database
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit query'
+_ssh_ -p <port> <host> _gerrit query_
   [--format {TEXT | JSON}]
   [--current-patch-set]
   [--patch-sets | --all-approvals]
@@ -115,20 +116,20 @@
 == EXAMPLES
 
 Find the 2 most recent open changes in the tools/gerrit project:
-====
+----
   $ ssh -p 29418 review.example.com gerrit query --format=JSON status:open project:tools/gerrit limit:2
   {"project":"tools/gerrit", ...}
   {"project":"tools/gerrit", ...}
   {"type":"stats","rowCount":2,"runningTimeMilliseconds:15}
-====
+----
 
 Skip number of changes:
-====
+----
   $ ssh -p 29418 review.example.com gerrit query --format=JSON --start 42 status:open project:tools/gerrit limit:2
   {"project":"tools/gerrit", ...}
   {"project":"tools/gerrit", ...}
   {"type":"stats","rowCount":1,"runningTimeMilliseconds:15}
-====
+----
 
 
 == SCHEMA
diff --git a/Documentation/cmd-receive-pack.txt b/Documentation/cmd-receive-pack.txt
index f3b4f02..798f872 100644
--- a/Documentation/cmd-receive-pack.txt
+++ b/Documentation/cmd-receive-pack.txt
@@ -4,8 +4,9 @@
 git-receive-pack - Receive what is pushed into the repository
 
 == SYNOPSIS
+[verse]
 --
-'git receive-pack'
+_git receive-pack_
   [--reviewer <address> | --re <address>]
   [--cc <address>]
   <project>
@@ -41,25 +42,25 @@
 == EXAMPLES
 
 Send a review for a change on the master branch to charlie@example.com:
-=====
+----
 	git push ssh://review.example.com:29418/project HEAD:refs/for/master%r=charlie@example.com
-=====
+----
 
 Send reviews, but tagging them with the topic name 'bug42':
-=====
+----
 	git push ssh://review.example.com:29418/project HEAD:refs/for/master%r=charlie@example.com,topic=bug42
-=====
+----
 
 Also CC two other parties:
-=====
+----
 	git push ssh://review.example.com:29418/project HEAD:refs/for/master%r=charlie@example.com,cc=alice@example.com,cc=bob@example.com
-=====
+----
 
 Configure a push macro to perform the last action:
-====
+----
 	git config remote.charlie.url ssh://review.example.com:29418/project
 	git config remote.charlie.push HEAD:refs/for/master%r=charlie@example.com,cc=alice@example.com,cc=bob@example.com
-====
+----
 
 afterwards `.git/config` contains the following:
 ----
@@ -70,9 +71,9 @@
 
 and now sending a new change for review to charlie, CC'ing both
 alice and bob is much easier:
-====
+----
 	git push charlie
-====
+----
 
 == SEE ALSO
 
diff --git a/Documentation/cmd-rename-group.txt b/Documentation/cmd-rename-group.txt
index 9578458..a48014c 100644
--- a/Documentation/cmd-rename-group.txt
+++ b/Documentation/cmd-rename-group.txt
@@ -4,8 +4,9 @@
 gerrit rename-group - Rename an account group.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit rename-group'
+_ssh_ -p <port> <host> _gerrit rename-group_
   <GROUP>
   <NEWNAME>
 --
@@ -30,9 +31,9 @@
 == EXAMPLES
 Rename the group "MyGroup" to "MyCommitters".
 
-====
+----
 	$ ssh -p 29418 user@review.example.com gerrit rename-group MyGroup MyCommitters
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-review.txt b/Documentation/cmd-review.txt
index 0590337..53e2385 100644
--- a/Documentation/cmd-review.txt
+++ b/Documentation/cmd-review.txt
@@ -1,12 +1,12 @@
-gerrit review
-==============
+= gerrit review
 
 == NAME
 gerrit review - Apply reviews to one or more patch sets
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit review'
+_ssh_ -p <port> <host> _gerrit review_
   [--project <PROJECT> | -p <PROJECT>]
   [--branch <BRANCH> | -b <BRANCH>]
   [--message <MESSAGE> | -m <MESSAGE>]
@@ -14,11 +14,13 @@
   [--submit | -s]
   [--abandon | --restore]
   [--rebase]
+  [--move <BRANCH>]
   [--publish]
   [--json | -j]
   [--delete]
   [--verified <N>] [--code-review <N>]
   [--label Label-Name=<N>]
+  [--tag TAG]
   {COMMIT | CHANGEID,PATCHSET}...
 --
 
@@ -65,7 +67,7 @@
 	link:rest-api-changes.html#review-input[ReviewInput] entity for the
 	format.
 	(option is mutually exclusive with --submit, --restore, --publish, --delete,
-	--abandon, --message and --rebase)
+	--abandon, --message, --rebase and --move)
 
 --notify::
 -n::
@@ -87,7 +89,7 @@
 --abandon::
 	Abandon the specified change(s).
 	(option is mutually exclusive with --submit, --restore, --publish, --delete,
-	--rebase and --json)
+	--rebase, --move and --json)
 
 --restore::
 	Restore the specified abandoned change(s).
@@ -97,6 +99,10 @@
 	Rebase the specified change(s).
 	(option is mutually exclusive with --abandon, --submit, --delete and --json)
 
+--move::
+	Move the specified change(s).
+	(option is mutually exclusive with --json and --abandon)
+
 --submit::
 -s::
 	Submit the specified patch set(s) for merging.
@@ -134,6 +140,15 @@
 	permitted for the user, or the vote is on an outdated or closed patch set,
 	return an error instead of silently discarding the vote.
 
+--tag::
+-t::
+  Apply a 'TAG' to the change message, votes, and inline comments. The 'TAG'
+  can represent an external system like CI that does automated verification
+  of the change. Comments with specific 'TAG' values can be filtered out in
+  the web UI.
+  Note that to apply different tags on on different votes/comments, multiple
+  invocations of the SSH command are required.
+
 == ACCESS
 Any user who has configured an SSH key.
 
@@ -143,37 +158,37 @@
 == EXAMPLES
 
 Approve the change with commit c0ff33 as "Verified +1"
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit review --verified +1 c0ff33
-=====
+----
 
 Vote on the project specific label "mylabel":
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit review --label mylabel=+1 c0ff33
-=====
+----
 
 Append the message "Build Successful". Notice two levels of quoting is
 required, one for the local shell, and another for the argument parser
 inside the Gerrit server:
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit review -m '"Build Successful"' c0ff33
-=====
+----
 
 Mark the unmerged commits both "Verified +1" and "Code-Review +2" and
 submit them for merging:
-====
+----
   $ ssh -p 29418 review.example.com gerrit review \
     --verified +1 \
     --code-review +2 \
     --submit \
     --project this/project \
     $(git rev-list origin/master..HEAD)
-====
+----
 
 Abandon an active change:
-====
+----
   $ ssh -p 29418 review.example.com gerrit review --abandon c0ff33
-====
+----
 
 == SEE ALSO
 
diff --git a/Documentation/cmd-set-account.txt b/Documentation/cmd-set-account.txt
index 8fb8e0d..884c8cc 100644
--- a/Documentation/cmd-set-account.txt
+++ b/Documentation/cmd-set-account.txt
@@ -4,14 +4,16 @@
 gerrit set-account - Change an account's settings.
 
 == SYNOPSIS
+[verse]
 --
-set-account [--full-name <FULLNAME>] [--active|--inactive] \
-            [--add-email <EMAIL>] [--delete-email <EMAIL> | ALL] \
-            [--preferred-email <EMAIL>] \
-            [--add-ssh-key - | <KEY>] \
-            [--delete-ssh-key - | <KEY> | ALL] \
-            [--http-password <PASSWORD>] \
-            [--clear-http-password] <USER>
+_ssh_ -p <port> <host> _gerrit set-account_
+  [--full-name <FULLNAME>] [--active|--inactive]
+  [--add-email <EMAIL>] [--delete-email <EMAIL> | ALL]
+  [--preferred-email <EMAIL>]
+  [--add-ssh-key - | <KEY>]
+  [--delete-ssh-key - | <KEY> | ALL]
+  [--http-password <PASSWORD>]
+  [--clear-http-password] <USER>
 --
 
 == DESCRIPTION
@@ -100,9 +102,9 @@
 == EXAMPLES
 Add an email and SSH key to `watcher`'s account:
 
-====
+----
     $ cat ~/.ssh/id_watcher.pub | ssh -p 29418 review.example.com gerrit set-account --add-ssh-key - --add-email mail@example.com watcher
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-set-head.txt b/Documentation/cmd-set-head.txt
index d74caaa..f444173 100644
--- a/Documentation/cmd-set-head.txt
+++ b/Documentation/cmd-set-head.txt
@@ -4,8 +4,9 @@
 gerrit set-head - Change a project's HEAD.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit set-head' <NAME>
+_ssh_ -p <port> <host> _gerrit set-head_ <NAME>
   --new-head <REF>
 --
 
@@ -33,9 +34,9 @@
 == EXAMPLES
 Change HEAD of project `example` to `stable-2.11` branch:
 
-====
+----
     $ ssh -p 29418 review.example.com gerrit set-head example --new-head stable-2.11
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-set-members.txt b/Documentation/cmd-set-members.txt
index 174a25a..ae44843 100644
--- a/Documentation/cmd-set-members.txt
+++ b/Documentation/cmd-set-members.txt
@@ -4,8 +4,9 @@
 gerrit set-members - Set group members
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit set-members'
+_ssh_ -p <port> <host> _gerrit set-members_
   [--add USER ...]
   [--remove USER ...]
   [--include GROUP ...]
@@ -57,18 +58,18 @@
 
 Add alice and bob, but remove eve from the groups my-committers and
 my-verifiers.
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit set-members \
 	  -a alice@example.com -a bob@example.com \
 	  -r eve@example.com my-committers my-verifiers
-=====
+----
 
 Include the group my-friends into the group my-committers, but
 exclude the included group my-testers from the group my-committers.
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit set-members \
 	  -i my-friends -e my-testers my-committers
-=====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-set-project-parent.txt b/Documentation/cmd-set-project-parent.txt
index 70918b2..6e2328c 100644
--- a/Documentation/cmd-set-project-parent.txt
+++ b/Documentation/cmd-set-project-parent.txt
@@ -4,8 +4,9 @@
 gerrit set-project-parent - Change the project permissions are inherited from.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit set-project-parent'
+_ssh_ -p <port> <host> _gerrit set-project-parent_
   [--parent <NAME>]
   [--children-of <NAME>]
   [--exclude <NAME>]
@@ -45,16 +46,16 @@
 == EXAMPLES
 Configure `kernel/omap` to inherit permissions from `kernel/common`:
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit set-project-parent --parent kernel/common kernel/omap
-====
+----
 
 Reparent all children of `myParent` to `myOtherParent`:
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit set-project-parent \
 	  --children-of myParent --parent myOtherParent
-====
+----
 
 == SEE ALSO
 
diff --git a/Documentation/cmd-set-project.txt b/Documentation/cmd-set-project.txt
index 2b64d77..62d6e92 100644
--- a/Documentation/cmd-set-project.txt
+++ b/Documentation/cmd-set-project.txt
@@ -4,8 +4,9 @@
 gerrit set-project - Change a project's settings.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit set-project'
+_ssh_ -p <port> <host> _gerrit set-project_
   [--description <DESC> | -d <DESC>]
   [--submit-type <TYPE> | -t <TYPE>]
   [--contributor-agreements <true|false|inherit>]
@@ -25,7 +26,7 @@
 previous settings are kept intact.
 
 == ACCESS
-Caller must be a member of the privileged 'Administrators' group.
+Caller must be an owner of the given project.
 
 == SCRIPTING
 This command is intended to be used in scripts.
@@ -102,10 +103,10 @@
 Change project `example` to be hidden, require change id, don't use content merge
 and use 'merge if necessary' as merge strategy:
 
-====
+----
     $ ssh -p 29418 review.example.com gerrit set-project example --submit-type MERGE_IF_NECESSARY\
     --change-id true --content-merge false --project-state HIDDEN
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-set-reviewers.txt b/Documentation/cmd-set-reviewers.txt
index 79f7651..3d53456 100644
--- a/Documentation/cmd-set-reviewers.txt
+++ b/Documentation/cmd-set-reviewers.txt
@@ -4,23 +4,23 @@
 gerrit set-reviewers - Add or remove reviewers to a change
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit set-reviewers'
+_ssh_ -p <port> <host> _gerrit set-reviewers_
   [--project <PROJECT> | -p <PROJECT>]
   [--add <REVIEWER> ... | -a <REVIEWER> ...]
   [--remove <REVIEWER> ... | -r <REVIEWER> ...]
   [--]
-  {COMMIT | CHANGE-ID}...
+  {CHANGE-ID}...
 --
 
 == DESCRIPTION
 Adds or removes reviewers to the specified change, sending email
 notifications when changes are made.
 
-Changes should be specified as complete or abbreviated Change-Ids
-such as 'Iac6b2ac2'.  They may also be specified by numeric change
-identifiers, such as '8242' or by complete or abbreviated commit
-SHA-1s.
+Changes can be specified in the
+link:rest-api-changes.html#change-id[same format] supported by the REST
+API.
 
 == OPTIONS
 
@@ -55,27 +55,27 @@
 == EXAMPLES
 
 Add reviewers alice and bob, but remove eve from change Iac6b2ac2.
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit set-reviewers \
 	  -a alice@example.com -a bob@example.com \
 	  -r eve@example.com \
 	  Iac6b2ac2
-=====
+----
 
 Add reviewer elvis to old-style change id 1935 specifying that the change is in project "graceland"
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit set-reviewers \
 	  --project graceland \
 	  -a elvis@example.com \
 	  1935
-=====
+----
 
 Add all project owners as reviewers to change Iac6b2ac2.
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit set-reviewers \
 	  -a "'Project Owners'" \
 	  Iac6b2ac2
-=====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-show-caches.txt b/Documentation/cmd-show-caches.txt
index 5d6ab20..59abc1c 100644
--- a/Documentation/cmd-show-caches.txt
+++ b/Documentation/cmd-show-caches.txt
@@ -1,12 +1,14 @@
-gerrit show-caches
-===================
+= gerrit show-caches
 
 == NAME
 gerrit show-caches - Display current cache statistics
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit show-caches' [--gc] [--show-jvm]
+_ssh_ -p <port> <host> _gerrit show-caches_
+  [--gc]
+  [--show-jvm]
 --
 
 == DESCRIPTION
@@ -48,7 +50,7 @@
 
 == EXAMPLES
 
-====
+----
   $ ssh -p 29418 review.example.com gerrit show-caches
   Gerrit Code Review        2.9                       now   11:14:13   CEST
                                                    uptime    6 days 20 hrs
@@ -87,7 +89,7 @@
            107 open files
 
   Threads: 4 CPUs available, 371 threads
-====
+----
 
 == SEE ALSO
 
diff --git a/Documentation/cmd-show-connections.txt b/Documentation/cmd-show-connections.txt
index 81eb174..2f70e3c 100644
--- a/Documentation/cmd-show-connections.txt
+++ b/Documentation/cmd-show-connections.txt
@@ -4,8 +4,10 @@
 gerrit show-connections - Display active client SSH connections
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit show-connections' [--numeric | -n]
+_ssh_ -p <port> <host> _gerrit show-connections_
+  [--numeric | -n]
 --
 
 == DESCRIPTION
@@ -40,7 +42,7 @@
 
 Start::
 	Time (local to the server) that this connection started.
-	Only valid for MINA backend.
+	Only shown for MINA backend.
 
 Idle::
 	Time since the last data transfer on this connection.
@@ -48,7 +50,7 @@
 	connection keep-alive, but also an encrypted keep alive
 	higher up in the SSH protocol stack.  That higher keep
 	alive resets the idle timer, about once a minute.
-	Only valid for MINA backend.
+	Only shown for MINA backend.
 
 User::
 	The username of the account that is authenticated on this
@@ -62,22 +64,22 @@
 == EXAMPLES
 
 With reverse DNS lookup (default):
-====
+----
 	$ ssh -p 29418 review.example.com gerrit show-connections
 	Session     Start     Idle   User            Remote Host
 	--------------------------------------------------------------
 	3abf31e6 20:09:02 00:00:00  jdoe            jdoe-desktop.example.com
 	--
-====
+----
 
 Without reverse DNS lookup:
-====
+----
 	$ ssh -p 29418 review.example.com gerrit show-connections -n
 	Session     Start     Idle   User            Remote Host
 	--------------------------------------------------------------
 	3abf31e6 20:09:02 00:00:00  a/1001240       10.0.0.1
 	--
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-show-queue.txt b/Documentation/cmd-show-queue.txt
index e3f44ab..02f1c5b 100644
--- a/Documentation/cmd-show-queue.txt
+++ b/Documentation/cmd-show-queue.txt
@@ -4,9 +4,10 @@
 gerrit show-queue - Display the background work queues, including replication
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit show-queue'
-'ssh' -p <port> <host> 'ps'
+_ssh_ -p <port> <host> _gerrit show-queue_
+_ssh_ -p <port> <host> _ps_
 --
 
 == DESCRIPTION
@@ -38,6 +39,10 @@
 	Do not format the output to the terminal width (default of
 	80 columns).
 
+--by-queue::
+-q::
+	Group tasks by queue and print queue info.
+
 == DISPLAY
 
 Task::
@@ -69,7 +74,7 @@
 `tools/gerrit.git` project to two different remote systems, `dst1`
 and `dst2`:
 
-====
+----
 	$ ssh -p 29418 review.example.com gerrit show-queue
 	Task     State                 Command
 	------------------------------------------------------------------------------
@@ -77,7 +82,7 @@
 	9ad09d27 14:31:25.434          mirror dst2:/var/cache/tools/gerrit.git
 	------------------------------------------------------------------------------
 	  2 tasks
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-stream-events.txt b/Documentation/cmd-stream-events.txt
index dcdbb07..1cfb8b9 100644
--- a/Documentation/cmd-stream-events.txt
+++ b/Documentation/cmd-stream-events.txt
@@ -4,8 +4,9 @@
 gerrit stream-events - Monitor events occurring in real time
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit stream-events'
+_ssh_ -p <port> <host> _gerrit stream-events_
 --
 
 == DESCRIPTION
@@ -26,13 +27,28 @@
 == SCRIPTING
 This command is intended to be used in scripts.
 
+== OPTIONS
+--subscribe|-s::
+	Type of the event to subscribe to.  Multiple --subscribe options
+	may be specified to subscribe to multiple events. When this option
+	is provided, only subscribed events are emitted and all other
+	events are ignored. When this option is omitted, all events are
+	emitted.
+
 == EXAMPLES
 
-====
+----
   $ ssh -p 29418 review.example.com gerrit stream-events
   {"type":"comment-added",change:{"project":"tools/gerrit", ...}, ...}
   {"type":"comment-added",change:{"project":"tools/gerrit", ...}, ...}
-====
+----
+
+Only subscribe to specific event types:
+
+----
+  $ ssh -p 29418 review.example.com gerrit stream-events \
+      -s draft-published -s patchset-created -s ref-replicated
+----
 
 == SCHEMA
 The JSON messages consist of nested objects referencing the *change*,
@@ -166,23 +182,6 @@
 eventCreatedOn:: Time in seconds since the UNIX epoch when this event was
 created.
 
-=== Merge Failed
-
-Sent when a change has failed to be merged into the git repository.
-
-type:: "merge-failed"
-
-change:: link:json.html#change[change attribute]
-
-patchSet:: link:json.html#patchSet[patchSet attribute]
-
-submitter:: link:json.html#account[account attribute]
-
-reason:: Reason that the merge failed.
-
-eventCreatedOn:: Time in seconds since the UNIX epoch when this event was
-created.
-
 === Patchset Created
 
 Sent when a new change has been uploaded, or a new patch set has been uploaded
@@ -232,6 +231,27 @@
 eventCreatedOn:: Time in seconds since the UNIX epoch when this event was
 created.
 
+=== Reviewer Deleted
+
+Sent when a reviewer (with a vote) is removed from a change.
+
+type:: "reviewer-deleted"
+
+change:: link:json.html#change[change attribute]
+
+patchSet:: link:json.html#patchSet[patchSet attribute]
+
+reviewer:: link:json.html#account[account attribute]
+
+author:: link:json.html#account[account attribute]
+
+approvals:: All link:json.html#approval[approval attributes] removed.
+
+comment:: Review comment cover message.
+
+eventCreatedOn:: Time in seconds since the UNIX epoch when this event was
+created.
+
 === Topic Changed
 
 Sent when the topic of a change has been changed.
diff --git a/Documentation/cmd-suexec.txt b/Documentation/cmd-suexec.txt
index f6ee753..16338ba 100644
--- a/Documentation/cmd-suexec.txt
+++ b/Documentation/cmd-suexec.txt
@@ -4,11 +4,12 @@
 suexec - Execute a command as any registered user account
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port>
+_ssh_ -p <port>
   -i SITE_PATH/etc/ssh_host_rsa_key
-  '"Gerrit Code Review@localhost"'
-  'suexec'
+  "Gerrit Code Review@localhost"
+  _suexec_
   --as <EMAIL>
   [--from HOST:PORT]
   [--]
@@ -47,7 +48,7 @@
 == EXAMPLES
 
 Approve the change with commit c0ff33 as "Verified +1" as user bob@example.com
-=====
+----
   $ sudo -u gerrit ssh -p 29418 \
     -i site_path/etc/ssh_host_rsa_key \
     "Gerrit Code Review@localhost" \
@@ -55,7 +56,7 @@
     --as bob@example.com \
     -- \
     gerrit approve --verified +1 c0ff33
-=====
+----
 
 GERRIT
 ------
diff --git a/Documentation/cmd-test-submit-rule.txt b/Documentation/cmd-test-submit-rule.txt
index a9a1bc4..b8c4380 100644
--- a/Documentation/cmd-test-submit-rule.txt
+++ b/Documentation/cmd-test-submit-rule.txt
@@ -4,8 +4,9 @@
 gerrit test-submit rule - Test prolog submit rules with a chosen changeset.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit test-submit rule'
+_ssh_ -p <port> <host> _gerrit test-submit_ rule
   [-s]
   [--no-filters]
   CHANGE
@@ -27,7 +28,7 @@
 == EXAMPLES
 
 Test submit_rule from stdin and return the results as JSON.
-====
+----
  cat rules.pl | ssh -p 29418 review.example.com gerrit test-submit rule -s I78f2c6673db24e4e92ed32f604c960dc952437d9
  [
    {
@@ -37,10 +38,10 @@
      }
    }
  ]
-====
+----
 
 Test the active submit_rule from the refs/meta/config branch, ignoring filters in the project parents.
-====
+----
  $ ssh -p 29418 review.example.com gerrit test-submit rule I78f2c6673db24e4e92ed32f604c960dc952437d9 --no-filters
  [
    {
@@ -51,7 +52,7 @@
      }
    }
  ]
-====
+----
 
 == SCRIPTING
 Can be used either interactively for testing new prolog submit rules, or from a script to check the submit status of a change.
diff --git a/Documentation/cmd-test-submit-type.txt b/Documentation/cmd-test-submit-type.txt
index 658d43b..508684f 100644
--- a/Documentation/cmd-test-submit-type.txt
+++ b/Documentation/cmd-test-submit-type.txt
@@ -4,8 +4,9 @@
 gerrit test-submit type - Test prolog submit type with a chosen change.
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit test-submit type'
+_ssh_ -p <port> <host> _gerrit test-submit_ type
   [-s]
   [--no-filters]
   CHANGE
@@ -27,16 +28,16 @@
 == EXAMPLES
 
 Test submit_type from stdin and return the submit type.
-====
+----
  cat rules.pl | ssh -p 29418 review.example.com gerrit test-submit type -s I78f2c6673db24e4e92ed32f604c960dc952437d9
  "MERGE_IF_NECESSARY"
-====
+----
 
 Test the active submit_type from the refs/meta/config branch, ignoring filters in the project parents.
-====
+----
  $ ssh -p 29418 review.example.com gerrit test-submit type I78f2c6673db24e4e92ed32f604c960dc952437d9 --no-filters
  "MERGE_IF_NECESSARY"
-====
+----
 
 == SCRIPTING
 Can be used either interactively for testing new prolog submit type, or from a script to check the submit type of a change.
diff --git a/Documentation/cmd-version.txt b/Documentation/cmd-version.txt
index d5c2263..cc797cc 100644
--- a/Documentation/cmd-version.txt
+++ b/Documentation/cmd-version.txt
@@ -4,8 +4,9 @@
 gerrit version - Show the version of the currently executing Gerrit server
 
 == SYNOPSIS
+[verse]
 --
-'ssh' -p <port> <host> 'gerrit version'
+_ssh_ -p <port> <host> _gerrit version_
 --
 
 == DESCRIPTION
@@ -32,10 +33,10 @@
 
 == EXAMPLES
 
-=====
+----
 	$ ssh -p 29418 review.example.com gerrit version
 	gerrit version 2.4.2
-=====
+----
 
 GERRIT
 ------
diff --git a/Documentation/config-auto-site-initialization.txt b/Documentation/config-auto-site-initialization.txt
index abd8d8f..acd03c9 100644
--- a/Documentation/config-auto-site-initialization.txt
+++ b/Documentation/config-auto-site-initialization.txt
@@ -8,53 +8,45 @@
 plugins will be installed when Gerrit is deployed in a servlet container
 and the location of the Gerrit distribution can be determined at
 runtime. It is also possible to install only a subset of packaged
-plugins or not install any plugin.
+plugins or not install any plugins.
 
 This feature may be useful for such setups where Gerrit administrators
 don't have direct access to the database and the file system of the
 server where Gerrit should be deployed and, therefore, cannot perform
 the init from their local machine prior to deploying Gerrit on such a
 server. It may also make deployment and testing in a local servlet
-container faster to setup as the init step could be skipped.
+container faster to set up as the init step could be skipped.
 
 == Gerrit Configuration
 
 The site initialization will be performed only if the `gerrit.init`
-system property exists (the value of the property is not used, only the
-existence of the property matters).
+system property exists. The value of the property is not used; only the
+existence of the property matters.
 
 If the `gerrit.site_path` system property is defined then the init is
 run for that site. The database connectivity, in that case, is defined
 in the `etc/gerrit.config`.
 
-If `gerrit.site_path` is not defined then Gerrit will try to find an
-existing site by looking into the `system_config` table in the database
-defined via the `jdbc/ReviewDb` JNDI property. If the `system_config`
-table exists then the `site_path` from that table is used for the
-initialization. The database connectivity is defined by the
-`jdbc/ReviewDb` JNDI property.
-
-Finally, if neither the `gerrit.site_path` property nor the
-`system_config` table exists, the `gerrit.init_path` system property,
-if defined, will be used to determine the site path. The database
-connectivity, also for this case, is defined by the `jdbc/ReviewDb`
-JNDI property.
+If `gerrit.site_path` is not defined then Gerrit will try to find the
+`gerrit.init_path` system property. If defined this property will be
+used to determine the site path. The database connectivity, also for
+this case, is defined by the `jdbc/ReviewDb` JNDI property.
 
 [WARNING]
 Defining the `jdbc/ReviewDb` JNDI property for an H2 database under the
 path defined by either `gerrit.site_path` or `gerrit.init_path` will
 cause an incomplete auto initialization and Gerrit will fail to start.
-Opening a connection to such database will create a subfolder under the
+Opening a connection to such a database will create a subfolder under the
 site path folder (in order to create the H2 database) and Gerrit will
-not any more consider that site path to be new and, because of that,
+no longer consider that site path to be new and, because of that,
 skip some required initialization steps (for example, Lucene index
 creation). In order to auto initialize Gerrit with an embedded H2
 database use the `gerrit.site_path` to define the location of the review
 site and don't define a JNDI resource with a URL under that path.
 
-If the 'gerrit.install_plugins' property is not defined then all packaged
+If the `gerrit.install_plugins` property is not defined then all packaged
 plugins will be installed. If it is defined then it is parsed as a
-comma separated list of plugin names to install. If the value is an
+comma-separated list of plugin names to install. If the value is an
 empty string then no plugin will be installed.
 
 === Example 1
@@ -70,18 +62,6 @@
 
 === Example 2
 
-Prepare Tomcat so that an existing site with the path defined in the
-`system_config` table is initialized (upgraded) on Gerrit startup. The
-assumption is that the `jdbc/ReviewDb` JNDI property is defined in
-Tomcat:
-
-----
-  $ export CATALINA_OPTS='-Dgerrit.init'
-  $ catalina.sh start
-----
-
-=== Example 3
-
 Assuming the database schema doesn't exist in the database defined
 via the `jdbc/ReviewDb` JNDI property, initialize a new site using that
 database and a given path:
diff --git a/Documentation/config-cla.txt b/Documentation/config-cla.txt
index 4c8d04a..c07a24f 100644
--- a/Documentation/config-cla.txt
+++ b/Documentation/config-cla.txt
@@ -12,27 +12,27 @@
 
 To retrieve the `project.config` file, initialize a temporary Git
 repository to edit the configuration:
-====
+----
   mkdir cfg_dir
   cd cfg_dir
   git init
-====
+----
 
 Download the existing configuration from Gerrit:
-====
+----
   git fetch ssh://localhost:29418/All-Projects refs/meta/config
   git checkout FETCH_HEAD
-====
+----
 
 Contributor agreements are defined as contributor-agreement sections in
 `project.config`:
-====
+----
   [contributor-agreement "Individual"]
     description = If you are going to be contributing code on your own, this is the one you want. You can sign this one online.
     agreementUrl = static/cla_individual.html
     autoVerify = group CLA Accepted - Individual
     accepted = group CLA Accepted - Individual
-====
+----
 
 Each `contributor-agreement` section within the `project.config` file must
 have a unique name. The section name will appear in the web UI.
@@ -41,10 +41,10 @@
 `autoVerify` and `accepted` variables in the groups file.
 
 Commit the configuration change, and push it back:
-====
+----
   git commit -a -m "Add Individual contributor agreement"
   git push ssh://localhost:29418/All-Projects HEAD:refs/meta/config
-====
+----
 
 [[contributor-agreement.name.description]]contributor-agreement.<name>.description::
 +
diff --git a/Documentation/config-gerrit.txt b/Documentation/config-gerrit.txt
index bc64d7f..211d174 100644
--- a/Documentation/config-gerrit.txt
+++ b/Documentation/config-gerrit.txt
@@ -19,6 +19,29 @@
   directory = /var/cache/gerrit2
 ----
 
+[[accountPatchReviewDb]]
+=== Section accountPatchReviewDb
+
+[[accountPatchReviewDb.url]]accountPatchReviewDb.url::
++
+The url of accountPatchReviewDb. Supported types are `H2`, `POSTGRESQL`, and
+`MYSQL`. Drop the driver jar in the lib folder of the site path if the Jdbc
+driver of the corresponding Database is not yet in the class path.
++
+Default is to create H2 database in the db folder of the site path.
++
+Changing this parameter requires to migrate database using the
+link:pgm-MigrateAccountPatchReviewDb.html[MigrateAccountPatchReviewDb] program.
+Migration cannot be done while the server is running.
++
+Also note that the db_name has to be a new db and not reusing gerrit's own review database,
+otherwise gerrit's init will remove the table.
+
+----
+[accountPatchReviewDb]
+  url = jdbc:postgresql://<host>:<port>/<db_name>?user=<user>&password=<password>
+----
+
 [[accounts]]
 === Section accounts
 
@@ -145,7 +168,7 @@
 The configured <<ldap.username,ldap.username>> identity is not used to obtain
 account information.
 +
-* OAUTH
+* `OAUTH`
 +
 OAuth is a protocol that lets external apps request authorization to private
 details in a user's account without getting their password. This is
@@ -383,6 +406,12 @@
 +
 If not set, HTTP request's path is used.
 
+[[auth.cookieDomain]]auth.cookieDomain::
++
+Sets "domain" attribute of the authentication cookie.
++
+If not set, HTTP request's domain is used.
+
 [[auth.cookieSecure]]auth.cookieSecure::
 +
 Sets "secure" flag of the authentication cookie.  If true, cookies
@@ -437,20 +466,73 @@
 [[auth.gitBasicAuth]]auth.gitBasicAuth::
 +
 If true then Git over HTTP and HTTP/S traffic is authenticated using
-standard BasicAuth and the credentials are validated against the randomly
-generated HTTP password or against LDAP when it is configured as Gerrit
-Web UI authentication method.
+standard BasicAuth. Depending on the configured `auth.type`, credentials
+are validated against the randomly generated HTTP password, against LDAP
+(`auth.type = LDAP`) or against an OAuth 2 provider (`auth.type = OAUTH`).
 +
 This parameter affects git over HTTP traffic and access to the REST
 API. If set to false then Gerrit will authenticate through DIGEST
 authentication and the randomly generated HTTP password in the Gerrit
 database.
 +
-When `auth.type` is `LDAP`, service users that only exist in the Gerrit
-database are still authenticated by their HTTP passwords.
+When `auth.type` is `LDAP`, users should authenticate using their LDAP passwords.
+However, if link:#auth.gitBasicAuthPolicy[`auth.gitBasicAuthPolicy`] is set to `HTTP`,
+the randomly generated HTTP password is used exclusively. In the other hand,
+if link:#auth.gitBasicAuthPolicy[`auth.gitBasicAuthPolicy`] is set to `HTTP_LDAP`,
+the password in the request is first checked against the HTTP password and, if
+it does not match, it is then validated against the LDAP password.
+Service users that only exist in the Gerrit database are authenticated by their
+HTTP passwords.
++
+When `auth.type` is `OAUTH`, Git clients may send OAuth 2 access tokens
+instead of passwords in the Basic authentication header. Note that provider
+specific plugins must be installed to facilitate this authentication scheme.
+If multiple OAuth 2 provider plugins are installed one of them must be
+selected as default with the `auth.gitOAuthProvider` option.
 +
 By default this is set to false.
 
+[[auth.gitBasicAuthPolicy]]auth.gitBasicAuthPolicy::
++
+When `auth.type` is `LDAP` and BasicAuth (i.e., link:#auth.gitBasicAuth[`auth.gitBasicAuth`]
+is set to true), it allows using either the generated HTTP password, the LDAP
+password or both to authenticate Git over HTTP and REST API requests. The
+supported values are:
++
+*`HTTP`
++
+Only the randomly generated HTTP password is accepted when doing Git over HTTP
+and REST API requests.
++
+*`LDAP`
++
+Only the `LDAP` password is allowed when doing Git over HTTP and REST API
+requests.
++
+*`HTTP_LDAP`
++
+The password in the request is first checked against the HTTP password and, if
+it does not match, it is then validated against the `LDAP` password.
++
+By default this is set to `LDAP` when link:#auth.type[`auth.type`] is `LDAP`.
+Otherwise, the default value is `HTTP`.
+
+[[auth.gitOAuthProvider]]auth.gitOAuthProvider::
++
+Selects the OAuth 2 provider to authenticate git over HTTP traffic with.
++
+In general there is no way to determine from an access token alone, which
+OAuth 2 provider to address to verify that token, and the BasicAuth
+scheme does not support amending such details. If multiple OAuth provider
+plugins in a system offer support for git over HTTP authentication site
+administrators must configure, which one to use as default provider.
+In case the provider cannot be determined from a request the access token
+will be sent to the default provider for verification.
++
+The value of this parameter must be the identifier of an OAuth 2 provider
+in the form `plugin-name:provider-name`. Consult the respective plugin
+documentation for details.
+
 [[auth.userNameToLowerCase]]auth.userNameToLowerCase::
 +
 If set the username that is received to authenticate a git operation
@@ -502,10 +584,40 @@
 expensive to compute information across restarts.  If the location
 does not exist, Gerrit will try to create it.
 +
+Technically, cached entities are persisted as a set of H2 databases
+inside this directory.
++
 If not absolute, the path is resolved relative to `$site_path`.
 +
 Default is unset, no disk cache.
 
+[[cache.h2CacheSize]]cache.h2CacheSize::
++
+The size of the in-memory cache for each opened H2 cache database, in bytes.
++
+Some caches of Gerrit are persistent and are backed by an H2 database.
+H2 uses memory to cache its database content. The parameter `h2CacheSize`
+allows to limit the memory used by H2 and thus prevent out-of-memory
+caused by the H2 database using too much memory.
++
+See <<database.h2.cachesize,database.h2.cachesize>> for a detailed discussion.
++
+Default is unset, using up to half of the available memory.
++
+H2 will persist this value in the database, so to unset explicitly specify 0.
++
+Common unit suffixes of 'k', 'm', or 'g' are supported.
+
+[[cache.h2AutoServer]]cache.h2AutoServer::
++
+If set to true, enable H2 autoserver mode for the H2-backed persistent cache
+databases.
++
+See link:http://www.h2database.com/html/features.html#auto_mixed_mode[here]
+for detail.
++
+Default is false.
+
 [[cache.name.maxAge]]cache.<name>.maxAge::
 +
 Maximum age to keep an entry in the cache. Entries are removed from
@@ -834,6 +946,33 @@
 +
 Default is the number of CPUs.
 
+
+[[capability]]
+=== Section capability
+
+[[capability.administrateServer]]capability.administrateServer::
++
+Names of groups of users that are allowed to exercise the
+administrateServer capability, in addition to those listed in
+All-Projects. Configuring this option can be a useful fail-safe
+to recover a server in the event an administrator removed all
+groups from the administrateServer capability, or to ensure that
+specific groups always have administration capabilities.
++
+----
+[capability]
+  administrateServer = group Fail Safe Admins
+----
++
+The configuration file uses group names, not UUIDs.  If a group is
+renamed the gerrit.config file must be updated to reflect the new
+name. If a group cannot be found for the configured name a warning
+is logged and the server will continue normal startup.
++
+If not specified (default), only the groups listed by All-Projects
+may use the administrateServer capability.
+
+
 [[change]]
 === Section change
 
@@ -867,6 +1006,12 @@
 +
 Default is 30 seconds.
 
+[[change.allowBlame]]change.allowBlame::
++
+Allow blame on side by side diff. If set to false, blame cannot be used.
++
+Default is true.
+
 [[change.allowDrafts]]change.allowDrafts::
 +
 Allow drafts workflow. If set to false, drafts cannot be created,
@@ -874,6 +1019,21 @@
 +
 Default is true.
 
+[[change.cacheAutomerge]]change.cacheAutomerge::
++
+When reviewing diff commits, the left-hand side shows the output of the
+result of JGit's automatic merge algorithm. This option controls whether
+this output is cached in the change repository, or if only the diff is
+cached in the persistent `diff` cache.
++
+If true, automerge results are stored in the repository under
+`refs/cache-automerge/*`; the results of diffing the change against its
+automerge base are stored in the diff cache. If false, no extra data is
+stored in the repository, only the diff cache. This can result in slight
+performance improvements by reducing the number of refs in the repo.
++
+Default is true.
+
 [[change.submitLabel]]change.submitLabel::
 +
 Label name for the submit button.
@@ -907,7 +1067,7 @@
 Default is "Submit all ${topicSize} changes of the same topic (${submitSize}
 changes including ancestors and other changes related by topic)".
 
-[[change.submitWholeTopic]]change.submitWholeTopic (*Experimental*)::
+[[change.submitWholeTopic]]change.submitWholeTopic::
 +
 Determines if the submit button submits the whole topic instead of
 just the current change.
@@ -924,7 +1084,7 @@
 
 [[change.submitTopicTooltip]]change.submitTopicTooltip::
 +
-If `change.submitWholeTopic` is configuerd to true and a change has a
+If `change.submitWholeTopic` is configured to true and a change has a
 topic, this configuration determines the tooltip for the submit button
 instead of `change.submitTooltip`. The variable `${topicSize}` is available
 for the number of changes in the same topic to be submitted. The number of
@@ -1038,25 +1198,6 @@
 +
 Default is 300 seconds (5 minutes).
 
-[[changeMerge.threadPoolSize]]changeMerge.threadPoolSize::
-+
-_Deprecated:_ Formerly used to control thread pool size for background
-mergeability checks. These checks were moved to the indexing threadpool,
-so this value is now used for
-link:#index.batchThreads[index.batchThreads], only if that value is not
-provided.
-+
-This option may be removed in a future version.
-
-[[changeMerge.interactiveThreadPoolSize]]changeMerge.interactiveThreadPoolSize::
-+
-_Deprecated:_ Formerly used to control thread pool size for interactive
-mergeability checks. These checks were moved to the indexing threadpool,
-so this value is now used for link:#index.threads[index.threads], only
-if that value is not provided.
-+
-This option may be removed in a future version.
-
 [[commentlink]]
 === Section commentlink
 
@@ -1199,6 +1340,12 @@
 called with the '--slave' switch, enabling slave mode. If no value is
 set (or any other value), Gerrit defaults to master mode.
 
+[[container.startupTimeout]]container.startupTimeout::
++
+The maximum time (in seconds) to wait for a gerrit.sh start command
+to run a new Gerrit daemon successfully.  If not set, defaults to
+90 seconds.
+
 [[container.user]]container.user::
 +
 Login name (or UID) of the operating system user the Gerrit JVM
@@ -1325,6 +1472,33 @@
 +
 Default is true.
 
+[[core.repositoryCacheCleanupDelay]]core.repositoryCacheCleanupDelay::
++
+Delay between each periodic cleanup of expired repositories.
++
+Values can be specified using standard time unit abbreviations (`ms`, `sec`,
+`min`, etc.).
++
+Set it to 0 in order to switch off cache expiration. If cache expiration is
+switched off, the JVM can still evict cache entries when it is running low
+on available heap memory.
++
+Set it to -1 to automatically derive cleanup delay from
+`core.repositoryCacheExpireAfter` (lowest value between 1/10 of
+`core.repositoryCacheExpireAfter` and 10 minutes).
++
+Default is -1.
+
+[[core.repositoryCacheExpireAfter]]core.repositoryCacheExpireAfter::
++
+Time an unused repository should expire and be evicted from the repository
+cache.
++
+Values can be specified using standard time unit abbreviations (`ms`, `sec`,
+`min`, etc.).
++
+Default is 1 hour.
+
 [[database]]
 === Section database
 
@@ -1435,7 +1609,8 @@
 httpd and sshd threads as some request processing code paths may
 need multiple connections.
 +
-Default is 8.
+Default is <<sshd.threads, sshd.threads>>
+ + <<httpd.maxThreads, httpd.maxThreads>> + 2.
 +
 This setting only applies if
 <<database.connectionPool,database.connectionPool>> is true.
@@ -1453,7 +1628,7 @@
 Maximum number of connections to keep idle in the pool.  If there
 are more idle connections, connections will be closed instead of
 being returned back to the pool.
-Default is 4.
+Default is min(<<database.poolLimit, database.poolLimit>>, 16).
 +
 This setting only applies if
 <<database.connectionPool,database.connectionPool>> is true.
@@ -1488,6 +1663,42 @@
 classpath, e. g. in `$gerrit_site/lib` directory. Example implementation of
 SQL monitoring can be found in javamelody-plugin.
 
+[[database.h2]]database.h2::
++
+The settings in this section are used for the reviewdb if the
+<<database.type,database.type>> is H2.
++
+Additionally gerrit uses H2 for storing reviewed flags on changes.
+
+[[database.h2.cacheSize]]database.h2.cacheSize::
++
+The size of the H2 internal database cache, in bytes. The H2 internal cache for
+persistent H2-backed caches is controlled by
+<<cache.h2CacheSize,cache.h2CacheSize>>.
++
+H2 uses memory to cache its database content. The parameter `cacheSize`
+allows to limit the memory used by H2 and thus prevent out-of-memory
+caused by the H2 database using too much memory.
++
+Technically the H2 cache size is configured using the CACHE_SIZE parameter in
+the H2 JDBC connection URL, as described
+link:http://www.h2database.com/html/features.html#cache_settings[here]
++
+Default is unset, using up to half of the available memory.
++
+H2 will persist this value in the database, so to unset explicitly specify 0.
++
+Common unit suffixes of 'k', 'm', or 'g' are supported.
+
+[[database.h2.autoServer]]database.h2.autoServer::
++
+If `true` enable the automatic mixed mode
+(see link:http://www.h2database.com/html/features.html#auto_mixed_mode[Automatic Mixed Mode]).
+This enables concurrent access to the embedded H2 database from command line
+utils (e.g. RebuildNoteDb).
++
+Default is `false`.
+
 [[download]]
 === Section download
 
@@ -1720,8 +1931,8 @@
 +
 The default URL for Gerrit to be accessed through.
 +
-Typically this would be set to "http://review.example.com/" or
-"http://example.com/gerrit/" so Gerrit can output links that point
+Typically this would be set to something like "http://review.example.com/"
+or "http://example.com:8080/gerrit/" so Gerrit can output links that point
 back to itself.
 +
 Setting this is highly recommended, as its necessary for the upload
@@ -1816,6 +2027,13 @@
 +
 If not specified, the default no-op implementation is used.
 
+[[gerrit.canLoadInIFrame]]gerrit.canLoadInIFrame::
++
+For security reasons Gerrit will always jump out of iframe.
+Setting this option to true will prevent this behavior.
++
+By default false.
+
 [[gitweb]]
 === Section gitweb
 
@@ -1830,29 +2048,31 @@
 be called by Gerrit Code Review when the URL `/gitweb` is accessed.
 Project level access controls are enforced prior to calling the CGI.
 +
-Defaults to `/usr/lib/cgi-bin/gitweb.cgi` if gitweb.url is not set.
+Defaults to `/usr/lib/cgi-bin/gitweb.cgi` if `gitweb.url` is not set.
 
 [[gitweb.url]]gitweb.url::
 +
 Optional URL of an affiliated gitweb service.  Defines the
 web location where a `gitweb.cgi` is installed to browse
-gerrit.basePath and the repositories it contains.
+`gerrit.basePath` and the repositories it contains.
 +
 Gerrit appends any necessary query arguments onto the end of this URL.
-For example, "?p=$project.git;h=$commit".
+For example, `?p=$project.git;h=$commit`.
 
 [[gitweb.type]]gitweb.type::
 +
 Optional type of affiliated gitweb service. This allows using
-alternatives to gitweb, such as cgit. If set to disabled there
-is no gitweb hyperlinking support.
+alternatives to gitweb, such as cgit.
 +
 Valid values are `gitweb`, `cgit`, `disabled` or `custom`.
++
+If not set, or set to `disabled`, there is no gitweb hyperlinking
+support.
 
 [[gitweb.revision]]gitweb.revision::
 +
 Optional pattern to use for constructing the gitweb URL when pointing
-at a specific commit when `custom` is used above.
+at a specific commit when `gitweb.type` is set to `custom`.
 +
 Valid replacements are `${project}` for the project name in Gerrit
 and `${commit}` for the SHA1 hash for the commit.
@@ -1860,14 +2080,14 @@
 [[gitweb.project]]gitweb.project::
 +
 Optional pattern to use for constructing the gitweb URL when pointing
-at a specific project when `custom` is used above.
+at a specific project when `gitweb.type` is set to `custom`.
 +
 Valid replacements are `${project}` for the project name in Gerrit.
 
 [[gitweb.branch]]gitweb.branch::
 +
 Optional pattern to use for constructing the gitweb URL when pointing
-at a specific branch when `custom` is used above.
+at a specific branch when `gitweb.type` is set to `custom`.
 +
 Valid replacements are `${project}` for the project name in Gerrit
 and `${branch}` for the name of the branch.
@@ -1875,8 +2095,8 @@
 [[gitweb.roottree]]gitweb.roottree::
 +
 Optional pattern to use for constructing the gitweb URL when pointing
-at the contents of the root tree in a specific commit when `custom` is
-used above.
+at the contents of the root tree in a specific commit when `gitweb.type`
+is set to `custom`.
 +
 Valid replacements are `${project}` for the project name in Gerrit
 and `${commit}` for the SHA1 hash for the commit.
@@ -1884,8 +2104,8 @@
 [[gitweb.file]]gitweb.file::
 +
 Optional pattern to use for constructing the gitweb URL when pointing
-at the contents of a file in a specific commit when `custom` is used
-above.
+at the contents of a file in a specific commit when `gitweb.type` is
+set to `custom`.
 +
 Valid replacements are `${project}` for the project name in Gerrit,
 `${file}` for the file name and `${commit}` for the SHA1 hash for
@@ -1894,8 +2114,8 @@
 [[gitweb.filehistory]]gitweb.filehistory::
 +
 Optional pattern to use for constructing the gitweb URL when pointing
-at the history of a file in a specific branch when `custom` is used
-above.
+at the history of a file in a specific branch when when `gitweb.type`
+is set to `custom`.
 +
 Valid replacements are `${project}` for the project name in Gerrit,
 `${file}` for the file name and `${branch}` for the name of the
@@ -1906,7 +2126,7 @@
 Optional setting for modifying the link name presented to the user
 in the Gerrit web-UI.
 +
-Default linkname for custom type is "gitweb".
+The default linkname for custom type is `gitweb`.
 
 [[gitweb.pathSeparator]]gitweb.pathSeparator::
 +
@@ -1921,9 +2141,9 @@
 allow using an alternative path separator character. In Gitblit, this can be
 configured through the property link:http://gitblit.com/properties.html[web.forwardSlashCharacter].
 In Gerrit, the alternative path separator can be configured correspondingly
-using the property 'gitweb.pathSeparator'.
+using the property `gitweb.pathSeparator`.
 +
-Valid values are the characters '*', '(' and ')'.
+Valid values are the characters `*`, `(` and `)`.
 
 [[gitweb.urlEncode]]gitweb.urlEncode::
 +
@@ -1931,22 +2151,12 @@
 +
 Gerrit composes the viewer URL using information about the project, branch, file
 or commit of the target object to be displayed. Typically viewers such as CGit
-and gitweb do need those parts to be encoded, including the '/' in project's name,
+and gitweb do need those parts to be encoded, including the `/` in project's name,
 for being correctly parsed.
 However other viewers could instead require an unencoded URL (e.g. GitHub web
-based viewer)
+based viewer).
 +
-Valid values are "true" and "false," default is "true."
-
-[[gitweb.linkDrafts]]gitweb.linkDrafts::
-+
-Whether or not Gerrit should provide links to gitweb on draft patch sets.
-+
-By default, Gerrit will show links to gitweb on all patch sets. If gitweb
-only allows publicly viewable references, set this to false to remove
-the links to draft patch sets from the change review screen.
-+
-Valid values are "true" and "false," default is "true".
+Valid values are `true` and `false`. The default is `true`.
 
 [[groups]]
 === Section groups
@@ -1958,90 +2168,6 @@
 +
 By default, false.
 
-[[hooks]]
-=== Section hooks
-
-See also link:config-hooks.html[Hooks].
-
-[[hooks.path]]hooks.path::
-+
-Optional path to hooks, if not specified then `'$site_path'/hooks` will be used.
-
-[[hooks.syncHookTimeout]]hooks.syncHookTimeout::
-+
-Optional timeout value in seconds for synchronous hooks, if not specified
-then 30 seconds will be used.
-
-[[hooks.changeAbandonedHook]]hooks.changeAbandonedHook::
-+
-Optional filename for the change abandoned hook, if not specified then
-`change-abandoned` will be used.
-
-[[hooks.changeMergedHook]]hooks.changeMergedHook::
-+
-Optional filename for the change merged hook, if not specified then
-`change-merged` will be used.
-
-[[hooks.changeRestoredHook]]hooks.changeRestoredHook::
-+
-Optional filename for the change restored hook, if not specified then
-`change-restored` will be used.
-
-[[hooks.claSignedHook]]hooks.claSignedHook::
-+
-Optional filename for the CLA signed hook, if not specified then
-`cla-signed` will be used.
-
-[[hooks.commentAddedHook]]hooks.commentAddedHook::
-+
-Optional filename for the comment added hook, if not specified then
-`comment-added` will be used.
-
-[[hooks.draftPublishedHook]]hooks.draftPublishedHook::
-+
-Optional filename for the draft published hook, if not specified then
-`draft-published` will be used.
-
-[[hooks.hashtagsChangedHook]]hooks.hashtagsChangedHook::
-+
-Optional filename for the hashtags changed hook, if not specified then
-`hashtags-changed` will be used.
-
-[[hooks.projectCreatedHook]]hooks.projectCreatedHook::
-+
-Optional filename for the project created hook, if not specified then
-`project-created` will be used.
-
-[[hooks.mergeFailedHook]]hooks.mergeFailedHook::
-+
-Optional filename for the merge failed hook, if not specified then
-`merge-failed` will be used.
-
-[[hooks.patchsetCreatedHook]]hooks.patchsetCreatedHook::
-+
-Optional filename for the patchset created hook, if not specified then
-`patchset-created` will be used.
-
-[[hooks.refUpdateHook]]hooks.refUpdateHook::
-+
-Optional filename for the ref update hook, if not specified then
-`ref-update` will be used.
-
-[[hooks.refUpdatedHook]]hooks.refUpdatedHook::
-+
-Optional filename for the ref updated hook, if not specified then
-`ref-updated` will be used.
-
-[[hooks.reviewerAddedHook]]hooks.reviewerAddedHook::
-+
-Optional filename for the reviewer added hook, if not specified then
-`reviewer-added` will be used.
-
-[[hooks.topicChangedHook]]hooks.topicChangedHook::
-+
-Optional filename for the topic changed hook, if not specified then
-`topic-changed` will be used.
-
 [[http]]
 === Section http
 
@@ -2151,6 +2277,14 @@
 +
 By default, true.
 
+[[httpd.inheritChannel]]httpd.inheritChannel::
++
+If true, permits the daemon to inherit its server socket channel
+from fd0/1(stdin/stdout). When set to true, the server can be socket
+activated via systemd or xinetd.
++
+By default, false.
+
 [[httpd.requestHeaderSize]]httpd.requestHeaderSize::
 +
 Size, in bytes, of the buffer used to parse the HTTP headers of an
@@ -2309,6 +2443,23 @@
 	filterClass = org.anyorg.MySecureFilter
 ----
 
+[[httpd.idleTimeout]]httpd.idleTimeout::
++
+Maximum idle time for a connection, which roughly translates to the
+TCP socket `SO_TIMEOUT`.
++
+This value is interpreted as the maximum time between some progress
+being made on the connection. So if a single byte is read or written,
+then the timeout is reset.
++
+The max idle time is applied:
++
+* When waiting for a new message to be received on a connection
+* When waiting for a new message to be sent on a connection
+
++
+By default, 30 seconds.
+
 [[httpd.robotsFile]]httpd.robotsFile::
 +
 Location of an external robots.txt file to be used instead of the one
@@ -2353,9 +2504,8 @@
 it to 0 disables the dedicated thread pool and indexing will be done in the same
 thread as the operation.
 +
-Defaults to 0 if not set, or set to a negative value (unless
-link:#changeMerge.interactiveThreadPoolSize[changeMerge.interactiveThreadPoolSize]
-is iset).
+If not set or set to a negative value, defaults to 1 plus half of the number of
+logical CPUs as returned by the JVM.
 
 [[index.batchThreads]]index.batchThreads::
 +
@@ -2363,8 +2513,7 @@
 online schema upgrades.
 +
 If not set or set to a negative value, defaults to the number of logical
-CPUs as returned by the JVM (unless
-link:#changeMerge.threadPoolSize[changeMerge.threadPoolSize] is set).
+CPUs as returned by the JVM.
 
 [[index.onlineUpgrade]]index.onlineUpgrade::
 +
@@ -2823,6 +2972,19 @@
   javaOptions = -Dcom.sun.jndi.ldap.connect.pool.timeout=300000
 ----
 
+[[lfs]]
+=== Section lfs
+
+[[lfs.plugin]]lfs.plugin::
++
+The name of a plugin which serves the
+link:https://github.com/github/git-lfs/blob/master/docs/api/v1/http-v1-batch.md[
+LFS protocol] on the `<project-name>/info/lfs/objects/batch` endpoint. When
+not configured Gerrit will respond with `501 Not Implemented` on LFS protocol
+requests.
++
+By default unset.
+
 [[log]]
 === Section log
 
@@ -2867,6 +3029,31 @@
   safe = true
 ----
 
+[[oauth]]
+=== Section oauth
+
+OAuth integration is only enabled if `auth.type` is set to `OAUTH`. See
+link:#auth.type[above] for a detailed description of the `auth.type` settings
+and their implications.
+
+By default, contact information, like the full name and email address,
+is retrieved from the selected OAuth provider when a user account is created,
+or when a user requests to reload that information in the settings UI. If
+that is not supported by the OAuth provider, users can be allowed to edit
+their contact information manually.
+
+[[oauth.allowEditFullName]]oauth.allowEditFullName::
++
+If true, the full name can be edited in the contact information.
++
+Default is false.
+
+[[oauth.allowRegisterNewEmail]]oauth.allowRegisterNewEmail::
++
+If true, additional email addresses can be registered in the contact
+information.
++
+Default is false.
 
 [[pack]]
 === Section pack
@@ -3117,10 +3304,22 @@
   defaultSubmitType = CHERRY_PICK
 ----
 
-[NOTE] All properties are used from the matching repository configuration. In
+[NOTE]
+All properties are used from the matching repository configuration. In
 the previous example, all properties will be used from `project/plugins/\*`
 section and no properties will be inherited nor overridden from `project/*`.
 
+[[repository.name.basePath]]repository.<name>.basePath::
++
+Alternate to <<gerrit.basePath,gerrit.basePath>>. The repository will be created
+and used from this location instead: ${alternateBasePath}/${projectName}.git.
++
+If configuring the basePath for an existing project in gerrit, make sure to stop
+gerrit, move the repository in the alternate basePath, configure basePath for
+this repository and then start Gerrit.
++
+Path must be absolute.
+
 [[repository.name.defaultSubmitType]]repository.<name>.defaultSubmitType::
 +
 The default submit type for newly created projects. Supported values
@@ -3171,6 +3370,28 @@
 +
 Default is 10x reductionLimit (1,000,000).
 
+[[rules.maxSourceBytes]]rules.maxSourceBytes::
++
+Maximum input size (in bytes) of a Prolog rules.pl file.  Larger
+source files may need a larger rules.compileReductionLimit.  Consider
+using link:pgm-rulec.html[rulec] to precompile larger rule files.
++
+A size of 0 bytes disables rules, same as rules.enable = false.
++
+Common unit suffixes of 'k', 'm', or 'g' are supported.
++
+Default is 128 KiB.
+
+[[rules.maxPrologDatabaseSize]]rules.maxPrologDatabaseSize::
++
+Number of predicate clauses allowed to be defined in the Prolog
+database by project rules.  Very complex rules may need more than the
+default 256 limit, but cost more memory and may need more time to
+evaluate.  Consider using link:pgm-rulec.html[rulec] to precompile
+larger rule files.
++
+Default is 256.
+
 [[execution]]
 === Section execution
 
@@ -3375,9 +3596,9 @@
 +
 Starting from version 0.9.0 Apache SSHD project added support for NIO2
 IoSession. To use the new NIO2 session the `backend` option must be set
-to `NIO2`.
+to `NIO2`. Otherwise, this option must be set to `MINA`.
 +
-By default, `MINA`.
+By default, `NIO2`.
 
 [[sshd.listenAddress]]sshd.listenAddress::
 +
@@ -3436,7 +3657,7 @@
 If additional requests are received while all threads are busy they
 are queued and serviced in a first-come-first-served order.
 +
-By default, 1.5x the number of CPUs available to the JVM.
+By default, 2x the number of CPUs available to the JVM.
 
 [[sshd.batchThreads]]sshd.batchThreads::
 +
@@ -3500,8 +3721,9 @@
 [[sshd.idleTimeout]]sshd.idleTimeout::
 +
 Time in seconds after which the server automatically terminates idle
-connections (or 0 to disable closing of idle connections).  Values
-should use common unit suffixes to express their setting:
+connections (or 0 to disable closing of idle connections) not waiting for
+any server operation to complete.
+Values should use common unit suffixes to express their setting:
 +
 * s, sec, second, seconds
 * m, min, minute, minutes
@@ -3511,6 +3733,21 @@
 +
 By default, 0.
 
+[[sshd.waitTimeout]]sshd.waitTimeout::
++
+Time in seconds after which the server automatically terminates
+connections waiting for a server operation to complete, like for instance
+cloning a very large repo with lots of refs.
+Values should use common unit suffixes to express their setting:
++
+* s, sec, second, seconds
+* m, min, minute, minutes
+* h, hr, hour, hours
+* d, day, days
+
++
+By default, 30s.
+
 [[sshd.maxConnectionsPerUser]]sshd.maxConnectionsPerUser::
 +
 Maximum number of concurrent SSH sessions that a user account
@@ -3547,6 +3784,40 @@
 +
 By default, all supported MACs are available.
 
+[[sshd.kex]]sshd.kex::
++
+--
+Available key exchange algorithms. To permit multiple algorithms,
+specify multiple `sshd.kex` keys in the configuration file, one key
+exchange algorithm per key.  Key exchange algorithm names starting
+with `+` are enabled in addition to the default key exchange
+algorithms, key exchange algorithm names starting with `-` are
+removed from the default key exchange algorithms.
+
+In the following example configuration, support for the 1024-bit
+`diffie-hellman-group1-sha1` key exchange is disabled while leaving
+all of the other default algorithms enabled:
+
+----
+[sshd]
+  kex = -diffie-hellman-group1-sha1
+----
+
+Supported key exchange algorithms:
+
+* `ecdh-sha2-nistp521`
+* `ecdh-sha2-nistp384`
+* `ecdh-sha2-nistp256`
+* `diffie-hellman-group-exchange-sha256`
+* `diffie-hellman-group-exchange-sha1`
+* `diffie-hellman-group14-sha1`
+* `diffie-hellman-group1-sha1`
+
+By default, all supported key exchange algorithms are available.
+Without Bouncy Castle, `diffie-hellman-group1-sha1` is the only
+available algorithm.
+--
+
 [[sshd.kerberosKeytab]]sshd.kerberosKeytab::
 +
 Enable kerberos authentication for SSH connections.  To permit
@@ -3606,35 +3877,12 @@
 [[suggest]]
 === Section suggest
 
-[[suggest.accounts]]suggest.accounts::
-+
-If `true`, visible user accounts (according to the value of
-`accounts.visibility`) will be offered as completion suggestions
-when adding a reviewer to a change, or a user to a group.
-+
-If `false`, account suggestion is disabled.
-+
-Older configurations may also have one of the `accounts.visibility`
-values for this field, including `OFF` as a synonym for `NONE`. If
-`accounts.visibility` is also set, that value overrides this one;
-otherwise, this value applies to both `suggest.accounts` and
-`accounts.visibility`.
-+
-New configurations should prefer the boolean value for this field
-and an enum value for `accounts.visibility`.
-
 [[suggest.maxSuggestedReviewers]]suggest.maxSuggestedReviewers::
 +
 The maximum numbers of reviewers suggested.
 +
 By default 10.
 
-[[suggest.fullTextSearch]]suggest.fullTextSearch::
-+
-If `true` the reviewer completion suggestions will be based on a full text search.
-+
-By default `false`.
-
 [[suggest.from]]suggest.from::
 +
 The number of characters that a user must have typed before suggestions
@@ -3642,18 +3890,6 @@
 +
 By default 0.
 
-[[suggest.fullTextSearchMaxMatches]]suggest.fullTextSearchMaxMatches::
-+
-The maximum number of matches evaluated for change access when using full text search.
-+
-By default 100.
-
-[[suggest.fullTextSearchRefresh]]suggest.fullTextSearchRefresh::
-+
-Refresh interval for the in-memory account search index.
-+
-By default 1 hour.
-
 
 [[theme]]
 === Section theme
@@ -3894,14 +4130,25 @@
 [[submodule]]
 === Section submodule
 
-[[submodule.verbosesuperprojectupdate]]submodule.verboseSuperprojectUpdate
+[[submodule.verbosesuperprojectupdate]]submodule.verboseSuperprojectUpdate::
 +
 When using link:user-submodules.html#automatic_update[automatic superproject updates]
-this option will determine if the submodule commit messages are included into
+this option will determine how the submodule commit messages are included into
 the commit message of the superproject update.
 +
-By default this is true.
+If `FALSE`, will not include any commit messages for the gitlink update.
++
+If `SUBJECT_ONLY`, will include only the commit subjects.
++
+If `TRUE`, will include full commit messages.
++
+By default this is `TRUE`.
 
+[[submodule.enableSuperProjectSubscriptions]]submodule.enableSuperProjectSubscriptions::
++
+This allows to enable the superproject subscription mechanism.
++
+By default this is true.
 
 [[user]]
 === Section user
diff --git a/Documentation/config-gitweb.txt b/Documentation/config-gitweb.txt
index 63eaffd..fcfd0e1 100644
--- a/Documentation/config-gitweb.txt
+++ b/Documentation/config-gitweb.txt
@@ -16,10 +16,10 @@
 which is a common installation path for the 'gitweb' package on
 Linux distributions.
 
-====
+----
   git config --file $site_path/etc/gerrit.config gitweb.cgi /usr/lib/cgi-bin/gitweb.cgi
   git config --file $site_path/etc/gerrit.config --unset gitweb.url
-====
+----
 
 Alternatively, if Gerrit is served behind reverse proxy, it can
 generate different URLs for gitweb's links (they need to be
@@ -27,10 +27,10 @@
 for serving gitweb under a different URL than the Gerrit instance.
 To enable this feature, set both: `gitweb.cgi` and `gitweb.url`.
 
-====
+----
   git config --file $site_path/etc/gerrit.config gitweb.cgi /usr/lib/cgi-bin/gitweb.cgi
   git config --file $site_path/etc/gerrit.config gitweb.url /pretty/path/to/gitweb
-====
+----
 
 After updating `'$site_path'/etc/gerrit.config`, the Gerrit server must
 be restarted and clients must reload the host page to see the change.
@@ -76,15 +76,15 @@
 
 On Ubuntu:
 
-====
-  sudo apt-get install gitweb
-====
+----
+  $ sudo apt-get install gitweb
+----
 
 With Yum:
 
-====
+----
   $ yum install gitweb
-====
+----
 
 ===== Configure Gitweb
 
@@ -124,16 +124,16 @@
 
 Link gitweb to `/var/www/gitweb`, check `/etc/gitweb.conf` if unsure of paths:
 
-====
+----
   $ sudo ln -s /usr/share/gitweb /var/www/gitweb
-====
+----
 
 Add the gitweb directory to the Apache configuration by creating a "gitweb"
 file inside the Apache conf.d directory:
 
-====
+----
   $ touch /etc/apache/conf.d/gitweb
-====
+----
 
 Add the following to /etc/apache/conf.d/gitweb:
 
@@ -145,14 +145,15 @@
 AllowOverride None
 ----
 
-*NOTE* This may have already been added by yum/apt-get. If that's the case, leave as
+[NOTE]
+This may have already been added by yum/apt-get. If that's the case, leave as
 is.
 
 ===== Restart the Apache Web Server
 
-====
-$ sudo /etc/init.d/apache2 restart
-====
+----
+  $ sudo /etc/init.d/apache2 restart
+----
 
 Now you should be able to view your repository projects online:
 
@@ -182,9 +183,9 @@
 verify by checking for perl modules. From an msys console, execute the
 following to check:
 
-====
+----
 $ perl -mCGI -mEncode -mFcntl -mFile::Find -mFile::Basename -e ""
-====
+----
 
 You may encounter the following exception:
 
diff --git a/Documentation/config-hooks.txt b/Documentation/config-hooks.txt
index 3068cc5..a71595f 100644
--- a/Documentation/config-hooks.txt
+++ b/Documentation/config-hooks.txt
@@ -1,190 +1,9 @@
 = Gerrit Code Review - Hooks
 
-Gerrit does not run any of the standard git hooks in the
-repositories it works with, but it does have its own hook mechanism
-included. Gerrit looks in `'$site_path'/hooks` for executables with
-names listed below.
-
-The environment will have GIT_DIR set to the full path of the
-affected git repository so that git commands can be easily run.
-
-Make sure your hook scripts are executable if running on *nix.
-
-With the exception of the ref-update hook, hooks are run in the background
-after the relevant change has taken place so are unable to affect
-the outcome of any given change. Because of the fact the hooks are
-run in the background after the activity, a hook might not be notified
-about an event if the server is shutdown before the hook can be invoked.
-
-== Supported Hooks
-
-=== ref-update
-
-This is called when a push request is received by Gerrit. It allows
-a push to be rejected before it is committed to the Gerrit repository.
-If the script exits with non-zero return code the push will be rejected.
-Any output from the script will be returned to the user, regardless of the
-return code.
-
-This hook is called synchronously so it is recommended that
-it not block.  A default timeout on the hook is set to 30 seconds to avoid
-"runaway" hooks using up server threads.  See link:config-gerrit.html#hooks.syncHookTimeout[hooks.syncHookTimeout]
-for configuration details.
-
-====
-  ref-update --project <project name> --refname <refname> --uploader <uploader> --oldrev <sha1> --newrev <sha1>
-====
-
-=== patchset-created
-
-This is called whenever a patchset is created (this includes new
-changes and drafts).
-
-====
-  patchset-created --change <change id> --is-draft <boolean> --kind <change kind> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --uploader <uploader> --commit <sha1> --patchset <patchset id>
-====
-
-kind:: change kind represents the kind of change uploaded, also represented in link:json.html#patchSet[patchSet]
-
-  REWORK;; Nontrivial content changes.
-
-  TRIVIAL_REBASE;; Conflict-free merge between the new parent and the prior patch set.
-
-  NO_CODE_CHANGE;; No code changed; same tree and same parent tree.
-
-  NO_CHANGE;; No changes; same commit message, same tree and same parent tree.
-
-=== draft-published
-
-This is called whenever a draft change is published.
-
-====
-  draft-published --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --uploader <uploader> --commit <sha1> --patchset <patchset id>
-====
-
-=== comment-added
-
-This is called whenever a comment is added to a change.
-
-====
-  comment-added --change <change id> --is-draft <boolean> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --author <comment author> --commit <commit> --comment <comment> [--<approval category id> <score> --<approval category id> <score> ...]
-====
-
-=== change-merged
-
-Called whenever a change has been merged.
-
-====
-  change-merged --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --submitter <submitter> --commit <sha1> --newrev <sha1>
-====
-
-=== merge-failed
-
-Called whenever a change has failed to merge.
-
-====
-  merge-failed --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --submitter <submitter> --commit <sha1> --reason <reason>
-====
-
-=== change-abandoned
-
-Called whenever a change has been abandoned.
-
-====
-  change-abandoned --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --abandoner <abandoner> --commit <sha1> --reason <reason>
-====
-
-=== change-restored
-
-Called whenever a change has been restored.
-
-====
-  change-restored --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --restorer <restorer> --commit <sha1> --reason <reason>
-====
-
-=== ref-updated
-
-Called whenever a ref has been updated.
-
-====
-  ref-updated --oldrev <old rev> --newrev <new rev> --refname <ref name> --project <project name> --submitter <submitter>
-====
-
-=== project-created
-
-Called whenever a project has been created.
-
-====
-  project-created --project <project name> --head <head name>
-====
-
-=== reviewer-added
-
-Called whenever a reviewer is added to a change.
-
-====
-  reviewer-added --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --reviewer <reviewer>
-====
-
-=== topic-changed
-
-Called whenever a change's topic is changed from the Web UI or via the REST API.
-
-====
-  topic-changed --change <change id> --change-owner <change owner> --project <project name> --branch <branch> --changer <changer> --old-topic <old topic> --new-topic <new topic>
-====
-
-=== hashtags-changed
-
-Called whenever hashtags are added to or removed from a change from the Web UI
-or via the REST API.
-
-====
-  hashtags-changed --change <change id>  --change-owner <change owner> --project <project name> --branch <branch> --editor <editor> --added <hashtag> --removed <hashtag> --hashtag <hashtag>
-====
-
-The `--added` parameter may be passed multiple times, once for each
-hashtag that was added to the change.
-
-The `--removed` parameter may be passed multiple times, once for each
-hashtag that was removed from the change.
-
-The `--hashtag` parameter may be passed multiple times, once for each
-hashtag remaining on the change after the add or remove operation has
-been performed.
-
-=== cla-signed
-
-Called whenever a user signs a contributor license agreement.
-
-====
-  cla-signed --submitter <submitter> --user-id <user_id> --cla-id <cla_id>
-====
-
-
-== Configuration Settings
-
-It is possible to change where Gerrit looks for hooks, and what
-filenames it looks for, by adding a [hooks] section in gerrit.config.
-
-Gerrit will use the value of hooks.path for the hooks directory.
-
-For the hook filenames, Gerrit will use the values of hooks.patchsetCreatedHook,
-hooks.draftPublishedHook, hooks.commentAddedHook, hooks.changeMergedHook,
-hooks.changeAbandonedHook, hooks.changeRestoredHook, hooks.refUpdatedHook,
-hooks.refUpdateHook, hooks.reviewerAddedHook and hooks.claSignedHook.
-
-== Missing Change URLs
-
-If link:config-gerrit.html#gerrit.canonicalWebUrl[gerrit.canonicalWebUrl]
-is not set in `gerrit.config` the `--change-url` flag may not be
-passed to all hooks.  Hooks started out of an SSH context (for example
-the patchset-created hook) don't know the server's web URL, unless
-this variable is configured.
-
-== SEE ALSO
-
-* link:config-gerrit.html#hooks[Section hooks]
+Gerrit does not run any of the standard git hooks in the repositories
+it works with, but it does have its own hook mechanism included via
+the link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/hooks[
+hooks plugin].
 
 GERRIT
 ------
diff --git a/Documentation/config-labels.txt b/Documentation/config-labels.txt
index a40c5f3..1f9dd33 100644
--- a/Documentation/config-labels.txt
+++ b/Documentation/config-labels.txt
@@ -90,13 +90,13 @@
 Administrators can install the Verified label by adding the following
 text to `project.config`:
 
-====
+----
   [label "Verified"]
       function = MaxWithBlock
       value = -1 Fails
       value =  0 No score
       value = +1 Verified
-====
+----
 
 The range of values is:
 
@@ -217,6 +217,19 @@
 The label is purely informational and values are not considered when
 determining whether a change is submittable.
 
+* `PatchSetLock`
++
+The `PatchSetLock` function provides a locking mechanism for patch
+sets.  This function's values are not considered when determining
+whether a change is submittable. When set, no new patchsets can be
+created and rebase and abandon are blocked.
++
+This function is designed to allow overlapping locks, so several lock
+accounts could lock the same change.
++
+Allowed range of values are 0 (Patch Set Unlocked) to 1 (Patch Set
+Locked).
+
 
 [[label_copyMinScore]]
 === `label.Label-Name.copyMinScore`
@@ -233,6 +246,23 @@
 sticky approvals, reducing turn-around for trivial cleanups prior to
 submitting a change. Defaults to false.
 
+[[label_copyAllScoresOnMergeCommitFirstParentUpdate]]
+=== `label.Label-Name.copyAllScoresOnMergeCommitFirstParentUpdate`
+
+This policy is useful if you don't want to trigger CI or human
+verification again if your target branch moved on but the feature
+branch being merged into the target branch did not change. It only
+applies if the patch set is a merge commit.
+
+If true, all scores for the label are copied forward when a new
+patch set is uploaded that is a new merge commit which only
+differs from the previous patch set in its first parent, or has
+identical parents. The first parent would be the parent of the merge
+commit that is part of the change's target branch, whereas the other
+parent(s) refer to the feature branch(es) to be merged.
+
+Defaults to false.
+
 [[label_copyAllScoresOnTrivialRebase]]
 === `label.Label-Name.copyAllScoresOnTrivialRebase`
 
@@ -240,10 +270,13 @@
 set is uploaded that is a trivial rebase. A new patch set is considered
 as trivial rebase if the commit message is the same as in the previous
 patch set and if it has the same code delta as the previous patch set.
-This is the case if the change was rebased onto a different parent.
+This is the case if the change was rebased onto a different parent, or
+if the parent did not change at all.
+
 This can be used to enable sticky approvals, reducing turn-around for
 trivial rebases prior to submitting a change.
 For the pre-installed Code-Review label this is enabled by default.
+
 Defaults to false.
 
 [[label_copyAllScoresIfNoCodeChange]]
@@ -257,6 +290,7 @@
 if only the commit message is changed prior to submitting a change.
 For the Verified label that is installed by the link:pgm-init.html[init]
 site program this is enabled by default.
+
 Defaults to false.
 
 [[label_copyAllScoresIfNoChange]]
@@ -268,7 +302,9 @@
 set SHA1 is different. This can be used to enable sticky
 approvals, reducing turn-around for this special case.
 It is recommended to leave this enabled for both Verified and
-Code-Review labels. Defaults to true.
+Code-Review labels.
+
+Defaults to true.
 
 [[label_canOverride]]
 === `label.Label-Name.canOverride`
@@ -287,16 +323,17 @@
 E.g. create a label `Video-Qualify` on parent project and configure
 the `branch` as:
 
-====
+----
   [label "Video-Qualify"]
       branch = refs/heads/video-1.0/*
       branch = refs/heads/video-1.1/Kino
-====
+----
 
 Then *only* changes in above branch scope of parent project and child
 projects will be affected by `Video-Qualify`.
 
-NOTE: The `branch` is independent from the branch scope defined in `access`
+[NOTE]
+The `branch` is independent from the branch scope defined in `access`
 parts in `project.config` file. That means from the UI a user can always
 assign permissions for that label on a branch, but this permission is then
 ignored if the label doesn't apply for that branch.
@@ -307,13 +344,13 @@
 To define a new 3-valued category that behaves exactly like `Verified`,
 but has different names/labels:
 
-====
+----
   [label "Copyright-Check"]
       function = MaxWithBlock
       value = -1 Do not have copyright
       value =  0 No score
       value = +1 Copyright clear
-====
+----
 
 The new column will appear at the end of the table, and `-1 Do not have
 copyright` will block submit, while `+1 Copyright clear` is required to
@@ -324,7 +361,7 @@
 This example attempts to describe how a label default value works with the
 user permissions.  Assume the configuration below.
 
-====
+----
   [access "refs/heads/*"]
       label-Snarky-Review = -3..+3 group Administrators
       label-Snarky-Review = -2..+2 group Project Owners
@@ -338,7 +375,7 @@
       value = +2 Hmm, this is pretty nice
       value = +3 Ohh, hell yes!
       defaultValue = -3
-====
+----
 
 Upon clicking the Reply button:
 
@@ -346,6 +383,20 @@
 * Project Owners have limited scores (-2..+2) available, -2 is set as the default.
 * Registered Users have limited scores (-1..+1) available, -1 is set as the default.
 
+=== Patch Set Lock Example
+
+This example shows how a label can be configured to have a standard patch set lock.
+
+----
+  [access "refs/heads/*"]
+      label-Patch-Set-Lock = +0..+1 group Administrators
+  [label "Patch-Set-Lock"]
+      function = PatchSetLock
+      value =  0 Patch Set Unlocked
+      value = +1 Patch Set Locked
+      defaultValue = 0
+----
+
 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/config-login-register.txt b/Documentation/config-login-register.txt
index 2e775b4..ffeae62 100644
--- a/Documentation/config-login-register.txt
+++ b/Documentation/config-login-register.txt
@@ -106,7 +106,8 @@
   user@host:~$
 ----
 
-IMPORTANT: Please take note of the extra line-breaks introduced in the key above
+[IMPORTANT]
+Please take note of the extra line-breaks introduced in the key above
 for formatting purposes. Please be sure to copy and paste your key without
 line-breaks.
 
diff --git a/Documentation/config-mail.txt b/Documentation/config-mail.txt
index da213a8..51ea9c5 100644
--- a/Documentation/config-mail.txt
+++ b/Documentation/config-mail.txt
@@ -56,6 +56,18 @@
 text that will be appended to emails related to a user submitting comments on
 changes.  See `ChangeSubject.vm`, `Comment.vm` and `ChangeFooter.vm`.
 
+=== DeleteVote.vm
+
+The `DeleteVote.vm` template will determine the contents of the email related
+to removing votes on changes.  It is a `ChangeEmail`: see `ChangeSubject.vm`
+and `ChangeFooter.vm`.
+
+=== DeleteReviewer.vm
+
+The `DeleteReviewer.vm` template will determine the contents of the email related
+to a user removing a reviewer (with a vote) from a change.  It is a
+`ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
+
 === Footer.vm
 
 The `Footer.vm` template will determine the contents of the footer text
@@ -68,12 +80,6 @@
 a change successfully merged to the head.  It is a `ChangeEmail`: see
 `ChangeSubject.vm` and `ChangeFooter.vm`.
 
-=== MergeFail.vm
-
-The `MergeFail.vm` template will determine the contents of the email related
-to a failure upon attempting to merge a change to the head.  It is a
-`ChangeEmail`: see `ChangeSubject.vm` and `ChangeFooter.vm`.
-
 === NewChange.vm
 
 The `NewChange.vm` template will determine the contents of the email related
diff --git a/Documentation/config-plugins.txt b/Documentation/config-plugins.txt
index ca95099..b7c1415 100644
--- a/Documentation/config-plugins.txt
+++ b/Documentation/config-plugins.txt
@@ -76,6 +76,18 @@
 link:https://gerrit.googlesource.com/plugins/download-commands/+doc/master/src/main/resources/Documentation/config.md[
 Configuration]
 
+[[hooks]]
+=== hooks
+
+This plugin runs server-side hooks on events.
+
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/hooks[
+Project] |
+link:https://gerrit.googlesource.com/plugins/hooks/+doc/master/src/main/resources/Documentation/about.md[
+Documentation] |
+link:https://gerrit.googlesource.com/plugins/hooks/+doc/master/src/main/resources/Documentation/config.md[
+Configuration]
+
 [[replication]]
 === replication
 
@@ -128,14 +140,12 @@
 these plugins.
 
 The Gerrit Project doesn't provide binaries for these plugins, but
-there are some public services that offer the download of pre-built
+there is one public service that offers the download of pre-built
 plugin jars:
 
 * link:https://gerrit-ci.gerritforge.com[CI Server from GerritForge]
-* link:http://builds.quelltextlich.at/gerrit/nightly/index.html[
-  CI Server from Quelltextlich]
 
-The following list gives an overview about available plugins, but the
+The following list gives an overview of available plugins, but the
 list may not be complete. You may discover more plugins on
 link:https://gerrit-review.googlesource.com/#/admin/projects/?filter=plugins%252F[
 gerrit-review].
@@ -154,24 +164,24 @@
 Documentation]
 
 [[avatars-external]]
-=== avatars/external
+=== avatars-external
 
 This plugin allows to use an external url to load the avatar images
 from.
 
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/avatars/external[
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/avatars-external[
 Project] |
-link:https://gerrit.googlesource.com/plugins/avatars/external/+doc/master/src/main/resources/Documentation/about.md[
+link:https://gerrit.googlesource.com/plugins/avatars-external/+doc/master/src/main/resources/Documentation/about.md[
 Documentation] |
-link:https://gerrit.googlesource.com/plugins/avatars/external/+doc/master/src/main/resources/Documentation/config.md[
+link:https://gerrit.googlesource.com/plugins/avatars-external/+doc/master/src/main/resources/Documentation/config.md[
 Configuration]
 
 [[avatars-gravatar]]
-=== avatars/gravatar
+=== avatars-gravatar
 
 Plugin to display user icons from Gravatar.
 
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/avatars/gravatar[
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/avatars-gravatar[
 Project]
 
 [[branch-network]]
@@ -197,20 +207,10 @@
 link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/changemessage[
 Project] |
 link:https://gerrit.googlesource.com/plugins/changemessage/+doc/master/src/main/resources/Documentation/about.md[
-Plugin Documenatation] |
+Plugin Documentation] |
 link:https://gerrit.googlesource.com/plugins/changemessage/+doc/master/src/main/resources/Documentation/config.md[
 Configuration]
 
-[[codenvy]]
-=== codenvy
-
-Plugin to allow to edit code on-line on either an existing branch or an
-active change using the link:http://codenvy.com[Codenvy] cloud
-development platform.
-
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/codenvy[
-Project]
-
 [[delete-project]]
 === delete-project
 
@@ -235,6 +235,18 @@
 link:https://gerrit.googlesource.com/plugins/egit/+doc/master/src/main/resources/Documentation/about.md[
 Documentation]
 
+[[emoticons]]
+=== emoticons
+
+This plugin allows users to see emoticons in comments as images.
+
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/emoticons[
+Project] |
+link:https://gerrit.googlesource.com/plugins/emoticons/+doc/master/src/main/resources/Documentation/about.md[
+Documentation] |
+link:https://gerrit.googlesource.com/plugins/emoticons/+doc/master/src/main/resources/Documentation/config.md[
+Configuration]
+
 [[force-draft]]
 === force-draft
 
@@ -406,6 +418,30 @@
 link:https://gerrit.googlesource.com/plugins/menuextender/+doc/master/src/main/resources/Documentation/config.md[
 Configuration]
 
+[[metrics-reporter-elasticsearch]]
+=== metrics-reporter-elasticsearch
+
+This plugin reports Gerrit metrics to Elasticsearch.
+
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/metrics-reporter-elasticsearch[
+Project].
+
+[[metrics-reporter-graphite]]
+=== metrics-reporter-graphite
+
+This plugin reports Gerrit metrics to Graphite.
+
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/metrics-reporter-graphite[
+Project].
+
+[[metrics-reporter-jmx]]
+=== metrics-reporter-jmx
+
+This plugin reports Gerrit metrics to JMX.
+
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/metrics-reporter-jmx[
+Project].
+
 [[motd]]
 === motd
 
@@ -546,6 +582,18 @@
 link:https://gerrit.googlesource.com/plugins/scripting/scala-provider/+doc/master/src/main/resources/Documentation/about.md[
 Documentation]
 
+[[scripts]]
+=== scripts
+
+Repository containing a collection of Gerrit scripting plugins that are intended
+to provide simple and useful extensions.
+
+Groovy and Scala scripts require the installation of the corresponding
+scripting/*-provider plugin in order to be loaded into Gerrit.
+
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/scripts[Project]
+link:https://gerrit.googlesource.com/plugins/scripts/+doc/master/README.md[Documentation]
+
 [[server-config]]
 === server-config
 
@@ -555,7 +603,7 @@
 where Gerrit's config files are stored is difficult or impossible to
 get.
 
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/scripting/server-config[
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/server-config[
 Project]
 
 [[serviceuser]]
@@ -568,7 +616,7 @@
 Plugin in Jenkins. A service user is not able to login into the Gerrit
 WebUI and it cannot push commits or tags.
 
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/scripting/serviceuser[
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/serviceuser[
 Project] |
 link:https://gerrit.googlesource.com/plugins/serviceuser/+doc/master/src/main/resources/Documentation/about.md[
 Documentation] |
@@ -584,22 +632,36 @@
 and a maximum allowed path length. Pushes of commits that violate these
 settings are rejected by Gerrit.
 
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/scripting/uploadvalidator[
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/uploadvalidator[
 Project] |
 link:https://gerrit.googlesource.com/plugins/uploadvalidator/+doc/master/src/main/resources/Documentation/about.md[
 Documentation] |
 link:https://gerrit.googlesource.com/plugins/uploadvalidator/+doc/master/src/main/resources/Documentation/config.md[
 Configuration]
 
+[[verify-status]]
+=== verify-status
+
+This plugin adds a separate channel for Gerrit to store test metadata and
+view them on the Gerrit UI.  The metadata can be stored in the Gerrit database
+or in a completely separate datastore.
+
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/verify-status[
+Project] |
+link:https://gerrit.googlesource.com/plugins/verify-status/+doc/master/src/main/resources/Documentation/about.md[
+Documentation] |
+link:https://gerrit.googlesource.com/plugins/verify-status/+doc/master/src/main/resources/Documentation/database.md[
+Configuration]
+
 [[websession-flatfile]]
 === websession-flatfile
 
 This plugin replaces the built-in Gerrit H2 based websession cache with
-a flatfile based implementation. This implemantation is shareable
+a flatfile based implementation. This implementation is shareable
 amongst multiple Gerrit servers, making it useful for multi-master
 Gerrit installations.
 
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/scripting/websession-flatfile[
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/websession-flatfile[
 Project] |
 link:https://gerrit.googlesource.com/plugins/websession-flatfile/+doc/master/src/main/resources/Documentation/about.md[
 Documentation] |
@@ -617,7 +679,7 @@
 Requests. Pushing a new patchset will reset the change to Review In
 Progress.
 
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/scripting/wip[
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/wip[
 Project] |
 link:https://gerrit.googlesource.com/plugins/wip/+doc/master/src/main/resources/Documentation/about.md[
 Documentation] |
@@ -629,7 +691,7 @@
 
 This plugin serves project documentation as HTML pages.
 
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/scripting/x-docs[
+link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/x-docs[
 Project] |
 link:https://gerrit.googlesource.com/plugins/x-docs/+doc/master/src/main/resources/Documentation/about.md[
 Documentation] |
diff --git a/Documentation/config-project-config.txt b/Documentation/config-project-config.txt
index 7d03681..7121265 100644
--- a/Documentation/config-project-config.txt
+++ b/Documentation/config-project-config.txt
@@ -65,8 +65,7 @@
 
 The link:#access-section[+access+ section] appears once per reference pattern,
 such as `+refs/*+` or `+refs/heads/*+`.  Only one access section per pattern is
-allowed.  You will find examples of keys and values in each category section
-<<access_category,below>>.
+allowed.
 
 The link:#receive-section[+receive+ section] appears once per project.
 
@@ -74,8 +73,7 @@
 
 The link:#capability-section[+capability+] section only appears once, and only
 in the +All-Projects+ repository.  It controls core features that are configured
-on a global level.  You can find examples of these
-<<capability_category,below>>.
+on a global level.
 
 The link:#label-section[+label+] section can appear multiple times. You can
 also redefine the text and behavior of the built in label types `Code-Review`
@@ -175,6 +173,22 @@
 Default is `INHERIT`, which means that this property is inherited from
 the parent project.
 
+[[receive.rejectImplicitMerges]]receive.rejectImplicitMerges::
++
+Controls whether a check for implicit merges will be performed when changes are
+pushed for review. An implicit merge is a case where merging an open change
+would implicitly merge another branch into the target branch. Typically, this
+happens when a change is done on master and, by mistake, pushed to a stable branch
+for review. When submitting such change, master would be implicitly merged into
+stable without anyone noticing that. When this option is set to 'true' Gerrit
+will reject the push if an implicit merge is detected.
++
+This check is only done for non-merge commits, merge commits are not subject of
+the implicit merge check.
++
+Default is `INHERIT`, which means that this property is inherited from
+the parent project.
+
 [[submit-section]]
 === Submit section
 
diff --git a/Documentation/config-sso.txt b/Documentation/config-sso.txt
index 897ca29..684b87c 100644
--- a/Documentation/config-sso.txt
+++ b/Documentation/config-sso.txt
@@ -10,9 +10,9 @@
 user authentication services.  To enable OpenID, the auth.type
 setting should be `OpenID`:
 
-====
+----
   git config --file $site_path/etc/gerrit.config auth.type OpenID
-====
+----
 
 As this is the default setting there is nothing required from the
 site administrator to make use of the OpenID authentication services.
@@ -24,9 +24,9 @@
 Add the following to `$JETTY_HOME/etc/jetty.xml` under
 `org.mortbay.jetty.nio.SelectChannelConnector`:
 
-====
+----
   <Set name="headerBufferSize">16384</Set>
-====
+----
 
 In order to use permissions beyond those granted to the
 `Anonymous Users` and `Registered Users` groups, an account
@@ -44,9 +44,9 @@
 * `https://` -- trust all OpenID providers using the HTTPS protocol
 
 To trust only Yahoo!:
-====
+----
   git config --file $site_path/etc/gerrit.config auth.trustedOpenID https://me.yahoo.com
-====
+----
 
 === Database Schema
 
@@ -100,11 +100,11 @@
 
 To enable this form of authentication:
 
-====
+----
   git config --file $site_path/etc/gerrit.config auth.type HTTP
   git config --file $site_path/etc/gerrit.config --unset auth.httpHeader
   git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com'
-====
+----
 
 The auth.type must always be HTTP, indicating the user identity
 will be obtained from the HTTP authorization data.
@@ -124,14 +124,14 @@
 such as the following is recommended to ensure Apache performs the
 authentication at the proper time:
 
-====
+----
   <Location "/login/">
     AuthType Basic
     AuthName "Gerrit Code Review"
     Require valid-user
     ...
   </Location>
-====
+----
 
 === Database Schema
 
@@ -161,11 +161,11 @@
 
 To enable this form of authentication:
 
-====
+----
   git config --file $site_path/etc/gerrit.config auth.type HTTP
   git config --file $site_path/etc/gerrit.config auth.httpHeader SM_USER
   git config --file $site_path/etc/gerrit.config auth.emailFormat '{0}@example.com'
-====
+----
 
 The auth.type must always be HTTP, indicating the user identity
 will be obtained from the HTTP authorization data.
@@ -186,9 +186,9 @@
 Add the following to `$JETTY_HOME/etc/jetty.xml` under
 `org.mortbay.jetty.nio.SelectChannelConnector`:
 
-====
+----
   <Set name="headerBufferSize">16384</Set>
-====
+----
 
 
 === Database Schema
diff --git a/Documentation/config-themes.txt b/Documentation/config-themes.txt
index b165e37..dcfd711 100644
--- a/Documentation/config-themes.txt
+++ b/Documentation/config-themes.txt
@@ -88,7 +88,7 @@
 To connect Gerrit to Google Analytics add the following to your
 `GerritSiteFooter.html`:
 
-====
+----
   <div>
   <!-- standard analytics code -->
     <script type="text/javascript">
@@ -110,7 +110,7 @@
     };
   </script>
   </div>
-====
+----
 
 Please consult the Google Analytics documentation for the correct
 setup code (the first two script tags).  The above is shown only
diff --git a/Documentation/config-validation.txt b/Documentation/config-validation.txt
index 27b39eb..2707e5c 100644
--- a/Documentation/config-validation.txt
+++ b/Documentation/config-validation.txt
@@ -21,16 +21,18 @@
 Out of the box, Gerrit includes a plugin that checks the length of the
 subject and body lines of commit messages on uploaded commits.
 
-[[ref-operation-validation]]
-== Ref operation validation
+[[user-ref-operations-validation]]
+== User ref operations validation
 
 
 Plugins implementing the `RefOperationValidationListener` interface can
-perform additional validation checks against ref creation/deletion operation
-before it is applied to the git repository.
+perform additional validation checks against user ref operations (resulting
+from either push or corresponding Gerrit REST/SSH endpoints call e.g.
+create branch etc.). Namely including ref creation, deletion and update
+(also non-fast-forward) before they are applied to the git repository.
 
-If the ref operation fails the validation, the plugin can throw an exception
-which will cause the operation to fail.
+The plugin can throw an exception which will cause the operation to fail,
+and prevent the ref update from being applied.
 
 [[pre-merge-validation]]
 == Pre-merge validation
diff --git a/Documentation/config.defs b/Documentation/config.defs
index 380080f..7f814d3 100644
--- a/Documentation/config.defs
+++ b/Documentation/config.defs
@@ -15,7 +15,7 @@
     'tilde="&#126;"',
     'last-update-label!',
     'source-highlighter=prettify',
-    'stylesheet=doc.css',
+    'stylesheet=DEFAULT',
     'linkcss=true',
     'prettifydir=.',
     'revnumber="%s"' % revision,
diff --git a/Documentation/database-setup.txt b/Documentation/database-setup.txt
index d720287..0f73bd3 100644
--- a/Documentation/database-setup.txt
+++ b/Documentation/database-setup.txt
@@ -40,7 +40,7 @@
 for larger installations. It's the database backend with the largest userbase
 in the Gerrit community.
 
-Create a user for the web application within Postgres, assign it a
+Create a user for the web application within PostgreSQL, assign it a
 password, create a database to store the metadata, and grant the user
 full rights on the newly created database:
 
@@ -207,6 +207,51 @@
         password = secret_pasword
 ----
 
+[[createdb_hana]]
+=== SAP HANA
+
+SAP HANA is a supported database for running Gerrit Code Review. However it is
+recommended only for environments where you intend to run Gerrit on an existing
+HANA installation to reduce administrative overhead.
+
+In the HANA studio or the SAP HANA Web-based Development Workbench create a user
+'GERRIT2' with the role 'RESTRICTED_USER_JDBC_ACCESS' and a password
+<secret password>. This will also create an associated schema on the database.
+As this user would be required to change the password upon first login you might
+want to to disable the password lifetime check by executing
+'ALTER USER GERRIT2 DISABLE PASSWORD LIFETIME'.
+
+To run Gerrit on HANA, you need to obtain the HANA JDBC driver. It can be found
+as described
+link:http://help.sap.com/saphelp_hanaplatform/helpdata/en/ff/15928cf5594d78b841fbbe649f04b4/frameset.htm[here].
+It needs to be stored in the 'lib' folder of the review site.
+
+In the following sample database section it is assumed that HANA is running on
+the host 'hana.host' with the instance number 00 where a schema/user GERRIT2
+was created:
+
+In $site_path/etc/gerrit.config:
+
+----
+[database]
+        type = hana
+        instance = 00
+        hostname = hana.host
+        username = GERRIT2
+
+----
+
+In $site_path/etc/secure.config:
+
+----
+[database]
+        password = <secret password>
+----
+
+Visit SAP HANA's link:http://help.sap.com/hana_appliance/[documentation] for
+further information regarding using SAP HANA.
+
+
 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/dev-buck.txt b/Documentation/dev-buck.txt
index ec8515f..315c0b0 100644
--- a/Documentation/dev-buck.txt
+++ b/Documentation/dev-buck.txt
@@ -3,11 +3,11 @@
 
 == Installation
 
-Note that you need to use Java 7 for building gerrit.
+You need to use Java 7 and Node.js for building gerrit.
 
 There is currently no binary distribution of Buck, so it has to be manually
-built and installed.  Apache Ant is required.  Currently only Linux and Mac
-OS are supported.
+built and installed.  Apache Ant and gcc are required.  Currently only Linux
+and Mac OS are supported.
 
 Clone the git and build it:
 
@@ -47,7 +47,7 @@
 ----
 
 To enable autocompletion of buck commands, install the autocompletion
-script from `./scripts/buck_completion.bash` in the buck project.  Refer
+script from `./scripts/buck-completion.bash` in the buck project.  Refer
 to the script's header comments for installation instructions.
 
 == Prerequisites
@@ -81,13 +81,15 @@
 
 === Attaching Sources
 
-To save time and bandwidth source JARs are only downloaded by the buck
-build where necessary to compile Java source into JavaScript using the
-GWT compiler.  Additional sources may be obtained, allowing Eclipse to
-show documentation or dive into the implementation of a library JAR:
+Source JARs are downloaded by default. This allows Eclipse to show
+documentation or dive into the implementation of a library JAR.
+
+To save time and bandwidth, download of source JARs can be restricted
+to only those that are necessary to compile Java source into JavaScript
+using the GWT compiler:
 
 ----
-  tools/eclipse/project.py --src
+  tools/eclipse/project.py --no-src
 ----
 
 
@@ -97,18 +99,34 @@
 
 === Gerrit Development WAR File
 
-To build the Gerrit web application:
+To build the Gerrit web application that includes GWT UI and PolyGerrit UI:
 
 ----
   buck build gerrit
 ----
 
+[NOTE]
+PolyGerrit UI may require additional tools (such as npm). Please read
+the polygerrit-ui/README.md for more info.
+
 The output executable WAR will be placed in:
 
 ----
   buck-out/gen/gerrit/gerrit.war
 ----
 
+To build the Gerrit web application that includes only GWT UI:
+
+----
+  buck build gwtgerrit
+----
+
+The output executable WAR will be placed in:
+
+----
+  buck-out/gen/gwtgerrit/gwtgerrit.war
+----
+
 
 === Headless Mode
 
@@ -144,13 +162,13 @@
 Install {extension,plugin,gwt}-api to the local maven repository:
 
 ----
-  buck build api_install
+  tools/maven/api.sh install
 ----
 
 Install gerrit.war to the local maven repository:
 
 ----
-  buck build war_install
+  tools/maven/api.sh war_install
 ----
 
 === Plugins
@@ -596,7 +614,7 @@
 The following tests should be executed, when Buck version is upgraded:
 
 * buck build release
-* buck build api_install
+* tools/maven/api.sh install
 * buck test
 * buck build gerrit, change some sources in gerrit-server project,
   repeat buck build gerrit and verify that gerrit.war was updated
@@ -617,7 +635,7 @@
 [known bug](https://github.com/facebook/buck/issues/341) related to
 symbolic links. The symbolic links are used very often with external
 plugins, that are linked per symbolic link to the plugins directory.
-With this use case Buck is failing to rebuild the plugin artefact
+With this use case Buck is failing to rebuild the plugin artifact
 after it was built. All attempts to convince Buck to rebuild will fail.
 The only known way to recover is to weep out `buck-out` directory. The
 better workaround is to avoid using Watchman in this specific use case.
@@ -625,30 +643,6 @@
 link:#buck-daemon[Using Buck daemon] section above how to temporarily
 disable `buckd`.
 
-=== Re-triggering rule execution
-
-There is no way to re-trigger custom rules with side effects, like
-`api_{deploy|install}`. This is a `genrule()` that depends on Java sources
-and is deploying the Plugin API through custom Python script to the local or
-remote Maven repositories. When for some reasons the deployment was undone,
-there is no supported way to re-trigger the execution of `api_{deploy|install}`
-targets. That's because `--no-cache` option will ignore the `Buck` cache, but
-there is no way to ignore `buck-out` directory. To overcome this Buck's design
-limitation new `tools/maven/api.py` script was added, that always re-triggers
-installation or deployment of Plugin API to local or Central Maven repository.
-
-```
-  tools/maven/api.py {deploy|install}
-```
-
-Dry run mode is also supported:
-
-```
-  tools/maven/api.py -n {deploy|install}
-```
-
-With this script the deployment would re-trigger on every invocation.
-
 == Troubleshooting Buck
 
 In some cases problems with Buck itself need to be investigated. See for example
diff --git a/Documentation/dev-build-plugins.txt b/Documentation/dev-build-plugins.txt
index 2c04d17..13071df 100644
--- a/Documentation/dev-build-plugins.txt
+++ b/Documentation/dev-build-plugins.txt
@@ -36,7 +36,7 @@
 * build and install `SNAPSHOT` version of plugin API in local Maven repository:
 
 ----
-buck build api_install
+./tools/maven/api.sh install
 ----
 
 === Exception 2:
diff --git a/Documentation/dev-contributing.txt b/Documentation/dev-contributing.txt
index 2d96b84..775fe21 100644
--- a/Documentation/dev-contributing.txt
+++ b/Documentation/dev-contributing.txt
@@ -164,7 +164,8 @@
     contributors may also like to open several editors side by
     side while editing new changes.
   * Use 2 spaces for indent (no tabs)
-  * Use brackets in all ifs, spaces before/after if parens.
+  * Use braces in all if/else/for/do/while/catch blocks, spaces before/after
+    if/for/while/catch parens.
   * Use /** */ style Javadocs for variables.
 
 Additionally, you will notice that most of the newline spacing
@@ -182,7 +183,7 @@
 Always:
 
   * final fields: marking fields as final forces them to be
-  initialised in the constructor or at declaration
+  initialized in the constructor or at declaration
   * final static fields: clearly communicates the intent
   * to use final variables in inner anonymous classes
 
@@ -360,7 +361,7 @@
 * Determine the sha1 hash of the zip file:
 +
 ----
- openssl sha1 4.10.0-6-gd0a2dda.zip
+ openssl sha1 codemirror-4.10.0-6-gd0a2dda.zip
 ----
 
 * Upload the zip file to the
diff --git a/Documentation/dev-eclipse.txt b/Documentation/dev-eclipse.txt
index b8d01e8..4fa542d 100644
--- a/Documentation/dev-eclipse.txt
+++ b/Documentation/dev-eclipse.txt
@@ -24,6 +24,12 @@
   Could not write generated class ... javax.annotation.processing.FilerException: Source file already created
 ----
 
+and
+
+----
+  AutoAnnotation_Commands_named cannot be resolved to a type
+----
+
 In Eclipse, choose 'Import existing project' and select the `gerrit` project
 from the current working directory.
 
diff --git a/Documentation/dev-inspector.txt b/Documentation/dev-inspector.txt
index 7c13a7d..2134f2f 100644
--- a/Documentation/dev-inspector.txt
+++ b/Documentation/dev-inspector.txt
@@ -4,14 +4,15 @@
 Gerrit Inspector - Interactive Jython environment for Gerrit
 
 == SYNOPSIS
+[verse]
 --
-'java' -jar gerrit.war 'daemon'
-	-d <SITE_PATH>
-	[\--enable-httpd | \--disable-httpd]
-	[\--enable-sshd | \--disable-sshd]
-	[\--console-log]
-	[\--slave]
-	-s
+_java_ -jar gerrit.war _daemon_
+  -d <SITE_PATH>
+  [--enable-httpd | --disable-httpd]
+  [--enable-sshd | --disable-sshd]
+  [--console-log]
+  [--slave]
+  -s
 --
 
 == DESCRIPTION
@@ -283,7 +284,8 @@
 == KNOWN ISSUES
 The Inspector does not yet recognize Google Guice bindings.
 
-IMPORTANT: Using the Inspector may void your warranty.
+[IMPORTANT]
+Using the Inspector may void your warranty.
 
 GERRIT
 ------
diff --git a/Documentation/dev-plugins.txt b/Documentation/dev-plugins.txt
index 254f511..2922a4e 100644
--- a/Documentation/dev-plugins.txt
+++ b/Documentation/dev-plugins.txt
@@ -36,7 +36,7 @@
 ----
 mvn archetype:generate -DarchetypeGroupId=com.google.gerrit \
     -DarchetypeArtifactId=gerrit-plugin-archetype \
-    -DarchetypeVersion=2.12.9-SNAPSHOT \
+    -DarchetypeVersion=2.13.12-SNAPSHOT \
     -DgroupId=com.googlesource.gerrit.plugins.testplugin \
     -DartifactId=testplugin
 ----
@@ -90,12 +90,11 @@
 Plugins may provide optional description information with standard
 manifest fields:
 
-====
+----
   Implementation-Title: Example plugin showing examples
   Implementation-Version: 1.0
   Implementation-Vendor: Example, Inc.
-  Implementation-URL: http://example.com/opensource/plugin-foo/
-====
+----
 
 === ApiType
 
@@ -105,9 +104,9 @@
 API will be assumed. This may cause ClassNotFoundExceptions when
 loading a plugin that needs the plugin API.
 
-====
+----
   Gerrit-ApiType: plugin
-====
+----
 
 === Explicit Registration
 
@@ -120,20 +119,20 @@
 will be performed by scanning all classes in the plugin JAR for
 `@Listen` and `@Export("")` annotations.
 
-====
+----
   Gerrit-Module:     tld.example.project.CoreModuleClassName
   Gerrit-SshModule:  tld.example.project.SshModuleClassName
   Gerrit-HttpModule: tld.example.project.HttpModuleClassName
-====
+----
 
 [[plugin_name]]
 === Plugin Name
 
 A plugin can optionally provide its own plugin name.
 
-====
+----
   Gerrit-PluginName: replication
-====
+----
 
 This is useful for plugins that contribute plugin-owned capabilities that
 are stored in the `project.config` file. Another use case is to be able to put
@@ -217,9 +216,9 @@
 be used, as it enables the server to hot-patch an updated plugin
 with no down time.
 
-====
+----
   Gerrit-ReloadMode: restart
-====
+----
 
 In either mode ('restart' or 'reload') any plugin or extension can
 be updated without restarting the Gerrit server. The difference is
@@ -260,9 +259,9 @@
 contribute their own "init step" to allow configuring the Jira URL,
 credentials and possibly verify connectivity to validate them.
 
-====
+----
   Gerrit-InitStep: tld.example.project.MyInitStep
-====
+----
 
 MyInitStep needs to follow the standard Gerrit InitStep syntax
 and behavior: writing to the console using the injected ConsoleUI
@@ -381,10 +380,16 @@
 
 * `com.google.gerrit.common.EventListener`:
 +
-Allows to listen to events. These are the same
-link:cmd-stream-events.html#events[events] that are also streamed by
+Allows to listen to events without user visibility restrictions. These
+are the same link:cmd-stream-events.html#events[events] that are also streamed by
 the link:cmd-stream-events.html[gerrit stream-events] command.
 
+* `com.google.gerrit.common.UserScopedEventListener`:
++
+Allows to listen to events visible to the specified user. These are the
+same link:cmd-stream-events.html#events[events] that are also streamed
+by the link:cmd-stream-events.html[gerrit stream-events] command.
+
 * `com.google.gerrit.extensions.events.LifecycleListener`:
 +
 Plugin start and stop
@@ -409,6 +414,14 @@
 +
 Garbage collection ran on a project
 
+* `com.google.gerrit.server.extensions.events.ChangeIndexedListener`:
++
+Update of the change secondary index
+
+* `com.google.gerrit.server.extensions.events.AccountIndexedListener`:
++
+Update of the account secondary index
+
 [[stream-events]]
 == Sending Events to the Events Stream
 
@@ -416,17 +429,49 @@
 Gerrit's `stream-events` ssh command will receive them.
 
 To send an event, the plugin must invoke one of the `postEvent`
-methods in the `ChangeHookRunner` class, passing an instance of
+methods in the `EventDispatcher` interface, passing an instance of
 its own custom event class derived from
 `com.google.gerrit.server.events.Event`.
 
+[source,java]
+----
+import com.google.gerrit.common.EventDispatcher;
+import com.google.gerrit.extensions.registration.DynamicItem;
+import com.google.gwtorm.server.OrmException;
+import com.google.inject.Inject;
+
+class MyPlugin {
+  private final DynamicItem<EventDispatcher> eventDispatcher;
+
+  @Inject
+  myPlugin(DynamicItem<EventDispatcher> eventDispatcher) {
+    this.eventDispatcher = eventDispatcher;
+  }
+
+  private void postEvent(MyPluginEvent event) {
+    try {
+      eventDispatcher.get().postEvent(event);
+    } catch (OrmException e) {
+      // error handling
+    }
+  }
+}
+----
+
 Plugins which define new Events should register them via the
 `com.google.gerrit.server.events.EventTypes.registerClass()`
 method. This will make the EventType known to the system.
-Deserialzing events with the
+Deserializing events with the
 `com.google.gerrit.server.events.EventDeserializer` class requires
 that the event be registered in EventTypes.
 
+== Modifying the Stream Event Flow
+
+It is possible to modify the stream event flow from plugins by registering
+an `com.google.gerrit.server.events.EventDispatcher`. A plugin may register
+a Dispatcher class to replace the internal Dispatcher. EventDispatcher is
+a DynamicItem, so Gerrit may only have one copy.
+
 [[validation]]
 == Validation Listeners
 
@@ -457,6 +502,12 @@
 for those plugins which would like to monitor usage in Git
 repositories.
 
+[[post-upload-hook]]
+== Post Upload-Pack Hooks
+
+Plugins may register PostUploadHook instances in order to get notified after
+JGit is done uploading a pack.
+
 [[ssh]]
 == SSH Commands
 
@@ -587,6 +638,48 @@
 $ ssh -p 29418 review.example.com sh ps
 ----
 
+[[search_operators]]
+=== Search Operators ===
+
+Plugins can define new search operators to extend change searching by
+implementing the `ChangeQueryBuilder.ChangeOperatorFactory` interface
+and registering it to an operator name in the plugin module's
+`configure()` method.  The search operator name is defined during
+registration via the DynamicMap annotation mechanism.  The plugin
+name will get appended to the annotated name, with an underscore
+in between, leading to the final operator name.  An example
+registration looks like this:
+
+    bind(ChangeOperatorFactory.class)
+       .annotatedWith(Exports.named("sample"))
+       .to(SampleOperator.class);
+
+If this is registered in the `myplugin` plugin, then the resulting
+operator will be named `sample_myplugin`.
+
+The search operator itself is implemented by ensuring that the
+`create()` method of the class implementing the
+`ChangeQueryBuilder.ChangeOperatorFactory` interface returns a
+`Predicate<ChangeData>`.  Here is a sample operator factory
+definition which creates a `MyPredicate`:
+
+[source,java]
+----
+@Singleton
+public class SampleOperator
+    implements ChangeQueryBuilder.ChangeOperatorFactory {
+  public static class MyPredicate extends OperatorChangePredicate<ChangeData> {
+    ...
+  }
+
+  @Override
+  public Predicate<ChangeData> create(ChangeQueryBuilder builder, String value)
+      throws QueryParseException {
+    return new MyPredicate(value);
+  }
+}
+----
+
 [[simple-configuration]]
 == Simple Configuration in `gerrit.config`
 
@@ -654,6 +747,18 @@
   reviewer = My Info Developers
 ----
 
+Plugins that have sensitive configuration settings can store those settings in
+an own secure configuration file. The plugin's secure configuration file must be
+named after the plugin and must be located in the `etc` folder of the review
+site. For example a secure configuration file for a `default-reviewer` plugin
+could look like this:
+
+.$site_path/etc/default-reviewer.secure.config
+----
+[auth]
+  password = secret
+----
+
 Via the `com.google.gerrit.server.config.PluginConfigFactory` class a
 plugin can easily access its configuration:
 
@@ -666,6 +771,8 @@
 
 String[] reviewers = cfg.getGlobalPluginConfig("default-reviewer")
                         .getStringList("branch", "refs/heads/master", "reviewer");
+String password = cfg.getGlobalPluginConfig("default-reviewer")
+                     .getString("auth", null, "password");
 ----
 
 
@@ -997,15 +1104,26 @@
 Panel will be shown in the header bar on the right side of the pop down
 buttons.
 
+** `GerritUiExtensionPoint.CHANGE_SCREEN_BELOW_COMMIT_INFO_BLOCK`:
++
+Panel will be shown below the commit info block.
+
 ** `GerritUiExtensionPoint.CHANGE_SCREEN_BELOW_CHANGE_INFO_BLOCK`:
 +
 Panel will be shown below the change info block.
 
+** `GerritUiExtensionPoint.CHANGE_SCREEN_BELOW_RELATED_INFO_BLOCK`:
++
+Panel will be shown below the related info block.
+
 ** The following parameters are provided:
 *** `GerritUiExtensionPoint.Key.CHANGE_INFO`:
 +
 The link:rest-api-changes.html#change-info[ChangeInfo] entity for the
 current change.
++
+The link:rest-api-changes.html#revision-info[RevisionInfo] entity for
+the current patch set.
 
 * Project Info Screen:
 ** `GerritUiExtensionPoint.PROJECT_INFO_SCREEN_TOP`:
@@ -1158,20 +1276,15 @@
   [...]
   // update change
   ReviewDb db = dbProvider.get();
-  db.changes().beginTransaction(change.getId());
-  try {
-    change = db.changes().atomicUpdate(
-      change.getId(),
-      new AtomicUpdate<Change>() {
-        @Override
-        public Change update(Change change) {
-          ChangeUtil.updated(change);
-          return change;
-        }
-      });
-    db.commit();
-  } finally {
-    db.rollback();
+  try (BatchUpdate bu = batchUpdateFactory.create(
+      db, project.getNameKey(), user, TimeUtil.nowTs())) {
+    bu.addOp(change.getId(), new BatchUpdate.Op() {
+      @Override
+      public boolean updateChange(BatchUpdate.ChangeContext ctx) {
+        return true;
+      }
+    });
+    bu.execute();
   }
   [...]
 }
@@ -1284,7 +1397,7 @@
 doesn't have to set `UiAction.Description.setVisible()` explicitly in this
 case.
 
-The following prerequisities must be met, to satisfy the capability check:
+The following prerequisites must be met, to satisfy the capability check:
 
 * user is authenticated
 * user is a member of a group which has the `Administrate Server` capability, or
@@ -1298,13 +1411,13 @@
 Every `UiAction` exposes a REST API endpoint. The endpoint from the example above
 can be accessed from any REST client, i. e.:
 
-====
+----
   curl -X POST -H "Content-Type: application/json" \
     -d '{message: "François", french: true}' \
     --digest --user joe:secret \
     http://host:port/a/changes/1/revisions/1/cookbook~say-hello
   "Bonjour François from change 1, patch set 1!"
-====
+----
 
 A special case is to bind an endpoint without a view name.  This is
 particularly useful for `DELETE` requests:
@@ -1746,7 +1859,7 @@
 
   @Inject
   public MyMenu(@PluginName String name) {
-    menuEntries = Lists.newArrayList();
+    menuEntries = new ArrayList<>();
     menuEntries.add(new MenuEntry("My Menu", Collections.singletonList(
       new MenuItem("My Screen", "#/x/" + name + "/my-screen", ""))));
   }
@@ -1912,6 +2025,32 @@
 No Guice bindings or modules are required. Gerrit will automatically
 discover and bind the implementation.
 
+[[accountcreation]]
+== Account Creation
+
+Plugins can hook into the
+link:rest-api-accounts.html#create-account[account creation] REST API and
+inject additional external identifiers for an account that represents a user
+in some external user store. For that, an implementation of the extension
+point `com.google.gerrit.server.api.accounts.AccountExternalIdCreator`
+must be registered.
+
+[source,java]
+----
+class MyExternalIdCreator implements AccountExternalIdCreator {
+  @Override
+  public List<AccountExternalId> create(Account.Id id, String username,
+      String email) {
+    // your code
+  }
+}
+
+bind(AccountExternalIdCreator.class)
+  .annotatedWith(UniqueAnnotations.create())
+  .to(MyExternalIdCreator.class);
+}
+----
+
 [[download-commands]]
 == Download Commands
 
@@ -1971,6 +2110,12 @@
 }
 ----
 
+ParentWebLinks will appear to the right of the SHA1 of the parent
+revisions in the UI. The implementation should in most use cases direct
+to the same external service as PatchSetWebLink; it is provided as a
+separate interface because not all users want to have links for the
+parent revisions.
+
 FileWebLinks will appear in the side-by-side diff screen on the right
 side of the patch selection on each side.
 
@@ -1982,6 +2127,144 @@
 
 BranchWebLinks will appear in the branch list in the last column.
 
+FileHistoryWebLinks will appear on the access rights screen.
+
+[[lfs-extension]]
+== LFS Storage Plugins
+
+Gerrit provides an extension point that enables development of
+link:https://github.com/github/git-lfs/blob/master/docs/api/v1/http-v1-batch.md[
+LFS (Large File Storage)] storage plugins. Gerrit core exposes the default LFS
+protocol endpoint `<project-name>/info/lfs/objects/batch` and forwards the requests
+to the configured link:config-gerrit.html#lfs[lfs.plugin] plugin which implements
+the LFS protocol. By exposing the default LFS endpoint, the git-lfs client can be
+used without any configuration.
+
+[source, java]
+----
+/** Provide an LFS protocol implementation */
+import org.eclipse.jgit.lfs.server.LargeFileRepository;
+import org.eclipse.jgit.lfs.server.LfsProtocolServlet;
+
+@Singleton
+public class LfsApiServlet extends LfsProtocolServlet {
+  private static final long serialVersionUID = 1L;
+
+  private final S3LargeFileRepository repository;
+
+  @Inject
+  LfsApiServlet(S3LargeFileRepository repository) {
+    this.repository = repository;
+  }
+
+  @Override
+  protected LargeFileRepository getLargeFileRepository() {
+    return repository;
+  }
+}
+
+/** Register the LfsApiServlet to listen on the default LFS protocol endpoint */
+import static com.google.gerrit.httpd.plugins.LfsPluginServlet.URL_REGEX;
+
+import com.google.gerrit.httpd.plugins.HttpPluginModule;
+
+public class HttpModule extends HttpPluginModule {
+
+  @Override
+  protected void configureServlets() {
+    serveRegex(URL_REGEX).with(LfsApiServlet.class);
+  }
+}
+
+/** Provide an implementation of the LargeFileRepository */
+import org.eclipse.jgit.lfs.server.s3.S3Repository;
+
+public class S3LargeFileRepository extends S3Repository {
+...
+}
+----
+
+[[metrics]]
+== Metrics
+
+=== Metrics Reporting
+
+To send Gerrit's metrics data to an external reporting backend, a plugin can
+get a `MetricRegistry` injected and register an instance of a class that
+implements the `Reporter` interface from link:http://metrics.dropwizard.io/[
+DropWizard Metrics].
+
+Metric reporting plugin implementations are provided for
+link:https://gerrit.googlesource.com/plugins/metrics-reporter-jmx/[JMX],
+link:https://gerrit.googlesource.com/plugins/metrics-reporter-elasticsearch/[Elastic Search],
+and link:https://gerrit.googlesource.com/plugins/metrics-reporter-graphite/[Graphite].
+
+There is also a working example of reporting metrics to the console in the
+link:https://gerrit.googlesource.com/plugins/cookbook-plugin/+/master/src/main/java/com/googlesource/gerrit/plugins/cookbook/ConsoleMetricReporter.java[
+cookbook plugin].
+
+=== Providing own metrics
+
+Plugins may provide metrics to be dispatched to external reporting services by
+getting a `MetricMaker` injected and creating instances of specific types of
+metric:
+
+* Counter
++
+Metric whose value increments during the life of the process.
+
+* Timer
++
+Metric recording time spent on an operation.
+
+* Histogram
++
+Metric recording statistical distribution (rate) of values.
+
+Note that metrics cannot be recorded from plugin init steps that
+are run during site initialization.
+
+By default, plugin metrics are recorded under
+`plugins/${plugin-name}/${metric-name}`. This can be changed by
+setting `plugins.${plugin-name}.metricsPrefix` in the `gerrit.config`
+file. For example:
+
+----
+  [plugin "my-plugin"]
+    metricsPrefix = my-metrics
+----
+
+will cause the metrics to be recorded under `my-metrics/${metric-name}`.
+
+See the replication metrics in the
+link:https://gerrit.googlesource.com/plugins/replication/+/master/src/main/java/com/googlesource/gerrit/plugins/replication/ReplicationMetrics.java[
+replication plugin] for an example of usage.
+
+[[account-patch-review-store]]
+== AccountPatchReviewStore
+
+The AccountPatchReviewStore is used to store reviewed flags on changes.
+A reviewed flag is a tuple of (patch set ID, file, account ID) and
+records whether the user has reviewed a file in a patch set. Each user
+can easily have thousands of reviewed flags and the number of reviewed
+flags is growing without bound. The store must be able handle this data
+volume efficiently.
+
+Gerrit implements this extension point, but plugins may bind another
+implementation, e.g. one that supports multi-master.
+
+----
+DynamicItem.bind(binder(), AccountPatchReviewStore.class)
+    .to(MultiMasterAccountPatchReviewStore.class);
+
+...
+
+public class MultiMasterAccountPatchReviewStore
+    implements AccountPatchReviewStore {
+  ...
+}
+----
+
 [[documentation]]
 == Documentation
 
diff --git a/Documentation/dev-release-deploy-config.txt b/Documentation/dev-release-deploy-config.txt
index b2c5358..921244f 100644
--- a/Documentation/dev-release-deploy-config.txt
+++ b/Documentation/dev-release-deploy-config.txt
@@ -142,8 +142,22 @@
   </distributionManagement>
 ----
 
+[NOTE]
+In case of JGit the `pom.xml` already contains a distributionManagement
+section.  Replace the existing distributionManagement section with this snippet
+in order to deploy the artifacts only in the gerrit-maven repository.
 
-* Add this to the `pom.xml` to enable the wagon provider:
+
+* Add these two snippets to the `pom.xml` to enable the wagon provider:
+
+----
+  <pluginRepositories>
+    <pluginRepository>
+      <id>gerrit-maven</id>
+      <url>https://gerrit-maven.commondatastorage.googleapis.com</url>
+    </pluginRepository>
+  </pluginRepositories>
+----
 
 ----
   <build>
diff --git a/Documentation/dev-release-jgit.txt b/Documentation/dev-release-jgit.txt
new file mode 100644
index 0000000..f6d4d68
--- /dev/null
+++ b/Documentation/dev-release-jgit.txt
@@ -0,0 +1,41 @@
+= Making a Release of JGit
+
+This step is only necessary if we need to create an unofficial JGit
+snapshot release and publish it to the
+link:https://developers.google.com/storage/[Google Cloud Storage].
+
+
+[[prepare-release]]
+== Prepare the Release
+
+Since JGit has its own release process we do not push any release tags
+for JGit. Instead we will use the output of the `git describe` as the
+version of the current JGit snapshot.
+
+----
+  ./tools/version.sh --release $(git describe)
+----
+
+
+[[publish-release]]
+== Publish the Release
+
+* Make sure you have done the configuration needed for deployment:
+** link:dev-release-deploy-config.html#deploy-configuration-settings-xml[
+Configuration in Maven `settings.xml`]
+** link:dev-release-deploy-config.html#deploy-configuration-subprojects[
+Configuration for Subprojects in `pom.xml`]
+
+* Deploy the new snapshot. From JGit workspace execute:
++
+----
+  mvn deploy
+----
+
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------
diff --git a/Documentation/dev-release-subproject.txt b/Documentation/dev-release-subproject.txt
index 9571edb..fcafea5 100644
--- a/Documentation/dev-release-subproject.txt
+++ b/Documentation/dev-release-subproject.txt
@@ -6,9 +6,9 @@
 * Build the latest snapshot and install it into the local Maven
 repository:
 +
-====
+----
   mvn clean install
-====
+----
 
 * Test Gerrit with this snapshot locally
 
@@ -27,9 +27,9 @@
 
 * Deploy the new snapshot:
 +
-====
+----
   mvn deploy
-====
+----
 
 * Change the `id`, `bin_sha1`, and `src_sha1` values in the `maven_jar`
 for the subproject in `/lib/BUCK` to the `SNAPSHOT` version.
@@ -50,15 +50,15 @@
 
 * Create the Release Tag
 +
-====
- git tag -a -m "prolog-cafe 1.3" v1.3
-====
+----
+  git tag -a -m "prolog-cafe 1.3" v1.3
+----
 
 * Build and install into local Maven repository:
 +
-====
+----
   mvn clean install
-====
+----
 
 
 [[publish-release]]
@@ -72,18 +72,18 @@
 
 * Deploy the new release:
 +
-====
+----
   mvn deploy
-====
+----
 
 * Push the pom change(s) to the project's repository
 `refs/for/<master|stable>`
 
 * Push the Release Tag
 +
-====
+----
   git push gerrit-review refs/tags/v1.3:refs/tags/v1.3
-====
+----
 
 
 GERRIT
diff --git a/Documentation/dev-release.txt b/Documentation/dev-release.txt
index 3157214..96695db 100644
--- a/Documentation/dev-release.txt
+++ b/Documentation/dev-release.txt
@@ -1,12 +1,10 @@
 = Making a Gerrit Release
 
 [NOTE]
-========================================================================
 This document is meant primarily for Gerrit maintainers
 who have been given approval and submit status to the Gerrit
 projects.  Additionally, maintainers should be given owner
 status to the Gerrit web site.
-========================================================================
 
 To make a Gerrit release involves a great deal of complex
 tasks and it is easy to miss a step so this document should
@@ -34,16 +32,12 @@
 * If needed create a Gerrit `RC1`
 
 [NOTE]
-========================================================================
 You may let in a few features to this release
-========================================================================
 
 * If needed create a Gerrit `RC2`
 
 [NOTE]
-========================================================================
 There should be no new features in this release, only bug fixes
-========================================================================
 
 * Finally create the `stable` release (no `RC`)
 
@@ -154,17 +148,26 @@
 [[build-gerrit]]
 === Build Gerrit
 
-* Build the Gerrit WAR and API JARs
+* Build the Gerrit WAR, API JARs and documentation
 +
 ----
   buck clean
-  buck build --no-cache release
-  buck build api_install
+  buck build --no-cache release docs
+  ./tools/maven/api.sh install
 ----
 
 * Sanity check WAR
 * Test the new Gerrit version
 
+* Verify plugin versions
++
+Sometimes `buck` doesn't rebuild plugins after they are tagged, and the
+versions don't reflect the tag. Verify the versions:
++
+----
+  java -jar ./buck-out/gen/release/release.war init --list-plugins
+----
+
 [[publish-gerrit]]
 === Publish the Gerrit Release
 
@@ -182,26 +185,19 @@
 * Push the WAR to Maven Central:
 +
 ----
-  buck build war_deploy
+  ./tools/maven/api.sh war_deploy
 ----
 
 * Push the plugin artifacts to Maven Central:
 +
 ----
-  buck build api_deploy
-----
-+
-For troubleshooting, the environment variable `VERBOSE` can be set. This
-prints out the commands that are executed by the Buck build process:
-+
-----
-  VERBOSE=1 buck build api_deploy
+  ./tools/maven/api.sh deploy
 ----
 +
 If no artifacts are uploaded, clean the `buck-out` folder and retry:
 +
 ----
-  rm -rf buck-out
+  buck clean ; rm -rf buck-out
 ----
 
 * Push the plugin Maven archetypes to Maven Central:
@@ -296,7 +292,8 @@
 [[publish-to-google-storage]]
 ==== Publish the Gerrit WAR to the Google Cloud Storage
 
-* go to https://console.developers.google.com/project/164060093628/storage/gerrit-releases/
+* go to the link:https://console.cloud.google.com/storage/browser/gerrit-releases/?project=api-project-164060093628[
+gerrit-releases bucket in the Google cloud storage console]
 * make sure you are signed in with your Gmail account
 * manually upload the Gerrit WAR file by using the `Upload` button
 
@@ -333,20 +330,18 @@
 * Build the release notes:
 +
 ----
-  make -C ReleaseNotes
+  buck build releasenotes
 ----
 
-* Build the documentation:
-+
-----
-  buck build docs
-----
+* Extract the release notes files from the zip file generated from the previous
+step: `buck-out/gen/ReleaseNotes/html/html.zip`.
 
-* Extract the documentation html files from the generated zip file
-`buck-out/gen/Documentation/searchfree.zip`.
+* Extract the documentation files from the zip file generated from
+`buck build docs`: `buck-out/gen/Documentation/searchfree/searchfree.zip`.
 
-* Upload the html files manually via web browser to the
-link:https://console.developers.google.com/project/164060093628/storage/gerrit-documentation/[
+* Upload the files manually via web browser to the appropriate folder
+in the
+link:https://console.cloud.google.com/storage/browser/gerrit-documentation/?project=api-project-164060093628[
 gerrit-documentation] storage bucket.
 
 [[update-links]]
@@ -358,20 +353,15 @@
 [[update-issues]]
 ==== Update the Issues
 
-====
- How do the issues get updated?  Do you run a script to do
- this?  When do you do it, after the final 2.5 is released?
-====
-
-By hand.
+Update the issues by hand. There is no script for this.
 
 Our current process is an issue should be updated to say `Status =
 Submitted, FixedIn-2.5` once the change is submitted, but before the
 release.
 
 After the release is actually made, you can search in Google Code for
-``Status=Submitted FixedIn=2.5'' and then batch update these changes
-to say `Status=Released`. Make sure the pulldown says ``All Issues''
+`Status=Submitted FixedIn=2.5` and then batch update these changes
+to say `Status=Released`. Make sure the pulldown says `All Issues`
 because `Status=Submitted` is considered a closed issue.
 
 
@@ -383,13 +373,12 @@
 ** A link to the release and the release notes (if a final release)
 ** A link to the docs
 ** Describe the type of release (stable, bug fix, RC)
-
-* Add an entry to the `NEWS` section of the main Gerrit project web page
-** Go to: http://code.google.com/p/gerrit/admin
-** Add entry like:
-----
- * Jun 14, 2012 - Gerrit 2.4.1 [https://groups.google.com/d/topic/repo-discuss/jHg43gixqzs/discussion Released]
-----
+** Hash values (SHA1, SHA256, MD5) for the release WAR file.
++
+The SHA1 and MD5 can be taken from the artifact page on Sonatype. The
+SHA256 can be generated with
+`openssl sha -sha256 buck-out/gen/release/release.war` or an equivalent
+command.
 
 * Update the new discussion group announcement to be sticky
 ** Go to: http://groups.google.com/group/repo-discuss/topics
diff --git a/Documentation/dev-stars.txt b/Documentation/dev-stars.txt
new file mode 100644
index 0000000..dfcbb6f
--- /dev/null
+++ b/Documentation/dev-stars.txt
@@ -0,0 +1,91 @@
+= Gerrit Code Review - Stars
+
+== Description
+
+Changes can be starred with labels that behave like private hashtags.
+Any label can be applied to a change, but these labels are only visible
+to the user for which the labels have been set.
+
+Stars allow users to categorize changes by self-defined criteria and
+then build link:user-dashboards.html[dashboards] for them by making use
+of the link:#query-stars[star query operators].
+
+[[star-api]]
+== Star API
+
+The link:rest-api-accounts.html#star-endpoints[star REST API] supports:
+
+* link:rest-api-accounts.html#get-stars[
+  get star labels from a change]
+* link:rest-api-accounts.html#set-stars[
+  update star labels on a change]
+* link:rest-api-accounts.html#get-starred-changes[
+  list changes that are starred by any label]
+
+Star labels are also included in
+link:rest-api-changes.html#change-info[ChangeInfo] entities that are
+returned by the link:rest-api-changes.html[changes REST API].
+
+There are link:rest-api-accounts.html#default-star-endpoints[
+additional REST endpoints] for the link:#default-star[default star].
+
+Only the link:#default-star[default star] is shown in the WebUI and
+can be updated from there. Other stars do not show up in the WebUI.
+
+[[default-star]]
+== Default Star
+
+If the default star is set by a user, this user is automatically
+notified by email whenever updates are made to that change.
+
+The default star is the star that is shown in the WebUI and which can
+be updated from there.
+
+The default star is represented by the special star label 'star'.
+
+[[ignore-star]]
+== Ignore Star
+
+If the ignore star is set by a user, this user gets no email
+notifications for updates of that change, even if this user is a
+reviewer of the change or the change is matched by a project watch of
+the user.
+
+Since changes can only be ignored once they are created, users that
+watch a project will always get the email notifications for the change
+creation. Only then the change can be ignored.
+
+Users that are added as reviewer to a change that they have ignored
+will be notified about this, so that they know about the review
+request. They can the decide to remove the ignore star.
+
+The ignore star is represented by the special star label 'ignore'.
+
+[[query-stars]]
+== Query Stars
+
+There are several query operators to find changes with stars:
+
+* link:user-search.html#star[star:<LABEL>]:
+  Matches any change that was starred by the current user with the
+  label `<LABEL>`.
+* link:user-search.html#has-stars[has:stars]:
+  Matches any change that was starred by the current user with any
+  label.
+* link:user-search.html#is-starred[is:starred] /
+  link:user-search.html#has-star[has:star]:
+  Matches any change that was starred by the current user with the
+  link:#default-star[default star].
+
+[[syntax]]
+== Syntax
+
+Star labels cannot contain whitespace characters. All other characters
+are allowed.
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------
diff --git a/Documentation/doc.css.in b/Documentation/doc.css.in
deleted file mode 100644
index 429e81c..0000000
--- a/Documentation/doc.css.in
+++ /dev/null
@@ -1,60 +0,0 @@
-body {
-  margin: 1em auto;
-  width: 900px;
-}
-
-#toctitle {
-  margin-top: 0.5em;
-  font-weight: bold;
-}
-
-h1, h2, h3, h4, h5, h6, #toctitle {
-  color: #527bbd;
-  font-family: sans-serif;
-}
-
-h1, h2, h3 {
-  border-bottom: 2px solid silver;
-}
-
-h1 {
-  margin-top: 1.5em;
-}
-
-p {
-  margin: 0.5em 0 0.5em 0;
-}
-li p {
-  margin: 0.2em 0 0.2em 0;
-}
-
-#license > .content,
-.listingblock > .content {
-  border: 2px solid silver;
-  background: #ebebeb;
-  margin-left: 2em;
-  color: darkgreen;
-  padding: 2px;
-  overflow: auto;
-}
-
-#license > .content pre,
-.listingblock > .content pre {
-  background: none;
-  border: 0 solid silver;
-  padding: 0 0 0 0;
-}
-
-dl dt {
-  margin-top: 1em;
-}
-
-table.tableblock {
-  border-collapse: collapse;
-}
-
-table.tableblock,
-th.tableblock,
-td.tableblock {
-  border: 1px solid #EEE;
-}
diff --git a/Documentation/error-has-duplicates.txt b/Documentation/error-has-duplicates.txt
index 8294c12..a520f5d 100644
--- a/Documentation/error-has-duplicates.txt
+++ b/Documentation/error-has-duplicates.txt
@@ -1,4 +1,4 @@
-= \... has duplicates
+= ... has duplicates
 
 With this error message Gerrit rejects to push a commit if its commit
 message contains a Change-Id for which multiple changes can be found
diff --git a/Documentation/error-messages.txt b/Documentation/error-messages.txt
index 16bc37b..2632254 100644
--- a/Documentation/error-messages.txt
+++ b/Documentation/error-messages.txt
@@ -20,7 +20,6 @@
 * link:error-missing-changeid.html[missing Change-Id in commit message footer]
 * link:error-missing-subject.html[missing subject; Change-Id must be in commit message footer]
 * link:error-multiple-changeid-lines.html[multiple Change-Id lines in commit message footer]
-* link:error-no-changes-made.html[no changes made]
 * link:error-no-common-ancestry.html[no common ancestry]
 * link:error-no-new-changes.html[no new changes]
 * link:error-non-fast-forward.html[non-fast forward]
@@ -32,7 +31,7 @@
 * link:error-permission-denied.html[Permission denied (publickey)]
 * link:error-prohibited-by-gerrit.html[prohibited by Gerrit]
 * link:error-project-not-found.html[Project not found: ...]
-* link:error-squash-commits-first.html[squash commits first]
+* link:error-same-change-id-in-multiple-changes.html[same Change-Id in multiple changes]
 * link:error-upload-denied.html[Upload denied for project \'...']
 * link:error-not-allowed-to-upload-merges.html[you are not allowed to upload merges]
 
diff --git a/Documentation/error-no-changes-made.txt b/Documentation/error-no-changes-made.txt
deleted file mode 100644
index 6182fcf..0000000
--- a/Documentation/error-no-changes-made.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-= no changes made
-
-With this error message Gerrit rejects to push a commit as a new
-patch set for a change, if the pushed commit is identical to the
-current patch set of this change.
-
-A pushed commit is considered to be identical to the current patch
-set if
-
-- the files in the commit,
-- the commit message,
-- the author of the commit and
-- the parents of the commit
-
-are all identical.
-
-
-GERRIT
-------
-Part of link:error-messages.html[Gerrit Error Messages]
-
-SEARCHBOX
----------
diff --git a/Documentation/error-same-change-id-in-multiple-changes.txt b/Documentation/error-same-change-id-in-multiple-changes.txt
new file mode 100644
index 0000000..b6aad69
--- /dev/null
+++ b/Documentation/error-same-change-id-in-multiple-changes.txt
@@ -0,0 +1,112 @@
+= same Change-Id in multiple changes
+
+With this error message Gerrit rejects to push a commit if it
+contains the same Change-Id as a predecessor commit.
+
+The reason for rejecting such a commit is that it would introduce, for
+the corresponding change in Gerrit, a dependency upon itself. Gerrit
+prevents such dependencies between patch sets within the same change
+to keep the review process simple. Otherwise reviewers would not only
+have to review the latest patch set but also all the patch sets the
+latest one depends on.
+
+This error is quite common, it appears when a user tries to address
+review comments and creates a new commit instead of amending the
+existing commit. Another possibility for this error, although less
+likely, is that the user tried to create a patch series with multiple
+changes to be reviewed and accidentally included the same Change-Id
+into the different commit messages.
+
+
+== Example
+
+Here an example about how the push is failing. Please note that the
+two commits 'one commit' and 'another commit' both have the same
+Change-Id (of course in real life it can happen that there are more
+than two commits that have the same Change-Id).
+
+----
+  $ git log
+  commit 13d381265ffff88088e1af88d0e2c2c1143743cd
+  Author: John Doe <john.doe@example.com>
+  Date:   Thu Dec 16 10:15:48 2010 +0100
+
+      another commit
+
+      Change-Id: I93478acac09965af91f03c82e55346214811ac79
+
+  commit ca45e125145b12fe9681864b123bc9daea501bf7
+  Author: John Doe <john.doe@example.com>
+  Date:   Thu Dec 16 10:12:54 2010 +0100
+
+      one commit
+
+      Change-Id: I93478acac09965af91f03c82e55346214811ac79
+
+  $ git push ssh://JohnDoe@host:29418/myProject HEAD:refs/for/master
+  Counting objects: 8, done.
+  Delta compression using up to 2 threads.
+  Compressing objects: 100% (2/2), done.
+  Writing objects: 100% (6/6), 558 bytes, done.
+  Total 6 (delta 0), reused 0 (delta 0)
+  To ssh://JohnDoe@host:29418/myProject
+  ! [remote rejected] HEAD -> refs/for/master (same Change-Id in multiple changes.
+  Squash the commits with the same Change-Id or ensure Change-Ids are unique for each commit)
+  error: failed to push some refs to 'ssh://JohnDoe@host:29418/myProject'
+
+----
+
+If it was the intention to rework a change and push a new patch
+set, the problem can be fixed by squashing the commits that contain the
+same Change-Id. The squashed commit can then be pushed to Gerrit.
+
+To squash the commits, use `git rebase -i` to do an interactive rebase. For
+the example above where the last two commits have the same Change-Id,
+this means an interactive rebase for the last two commits should be
+done. For further details about the git rebase command please check
+the link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[Git documentation for rebase].
+
+----
+  $ git rebase -i HEAD~2
+
+  pick ca45e12 one commit
+  squash 13d3812 another commit
+
+  [detached HEAD ab37207] squashed commit
+   1 files changed, 3 insertions(+), 0 deletions(-)
+  Successfully rebased and updated refs/heads/master.
+
+  $ git log
+  commit ab37207d33647685801dba36cb4fd51f3eb73507
+  Author: John Doe <john.doe@example.com>
+  Date:   Thu Dec 16 10:12:54 2010 +0100
+
+      squashed commit
+
+      Change-Id: I93478acac09965af91f03c82e55346214811ac79
+
+  $ git push ssh://JohnDoe@host:29418/myProject HEAD:refs/for/master
+  Counting objects: 5, done.
+  Writing objects: 100% (3/3), 307 bytes, done.
+  Total 3 (delta 0), reused 0 (delta 0)
+  To ssh://JohnDoe@host:29418/myProject
+   * [new branch]      HEAD -> refs/for/master
+----
+
+If it was the intention to create a patch series with multiple
+changes to be reviewed, each commit message should contain the
+Change-Id of the corresponding change in Gerrit.  If a change in
+Gerrit does not exist yet, the Change-Id should be generated (either
+by using a link:cmd-hook-commit-msg.html[commit hook] or by using EGit) or the Change-Id could be
+removed (not recommended since then amending this commit to create
+subsequent patch sets is more error prone). To change the Change-Id
+of an existing commit do an interactive link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[git rebase] and fix the
+affected commit messages.
+
+
+GERRIT
+------
+Part of link:error-messages.html[Gerrit Error Messages]
+
+SEARCHBOX
+---------
diff --git a/Documentation/error-squash-commits-first.txt b/Documentation/error-squash-commits-first.txt
deleted file mode 100644
index 4069d5b..0000000
--- a/Documentation/error-squash-commits-first.txt
+++ /dev/null
@@ -1,110 +0,0 @@
-= squash commits first
-
-With this error message Gerrit rejects to push a commit if it
-contains the same Change-Id as a predecessor commit.
-
-The reason for rejecting such a commit is that it would introduce, for
-the corresponding change in Gerrit, a dependency upon itself. Gerrit
-prevents such dependencies between patch sets within the same change
-to keep the review process simple. Otherwise reviewers would not only
-have to review the latest patch set but also all the patch sets the
-latest one depends on.
-
-This error is quite common, it appears when a user tries to address
-review comments and creates a new commit instead of amending the
-existing commit. Another possibility for this error, although less
-likely, is that the user tried to create a patch series with multiple
-changes to be reviewed and accidentally included the same Change-Id
-into the different commit messages.
-
-
-== Example
-
-Here an example about how the push is failing. Please note that the
-two commits 'one commit' and 'another commit' both have the same
-Change-Id (of course in real life it can happen that there are more
-than two commits that have the same Change-Id).
-
-----
-  $ git log
-  commit 13d381265ffff88088e1af88d0e2c2c1143743cd
-  Author: John Doe <john.doe@example.com>
-  Date:   Thu Dec 16 10:15:48 2010 +0100
-
-      another commit
-
-      Change-Id: I93478acac09965af91f03c82e55346214811ac79
-
-  commit ca45e125145b12fe9681864b123bc9daea501bf7
-  Author: John Doe <john.doe@example.com>
-  Date:   Thu Dec 16 10:12:54 2010 +0100
-
-      one commit
-
-      Change-Id: I93478acac09965af91f03c82e55346214811ac79
-
-  $ git push ssh://JohnDoe@host:29418/myProject HEAD:refs/for/master
-  Counting objects: 8, done.
-  Delta compression using up to 2 threads.
-  Compressing objects: 100% (2/2), done.
-  Writing objects: 100% (6/6), 558 bytes, done.
-  Total 6 (delta 0), reused 0 (delta 0)
-  To ssh://JohnDoe@host:29418/myProject
-   ! [remote rejected] HEAD -> refs/for/master (squash commits first)
-  error: failed to push some refs to 'ssh://JohnDoe@host:29418/myProject'
-----
-
-If it was the intention to rework a change and push a new patch
-set, the problem can be fixed by squashing the commits that contain the
-same Change-Id. The squashed commit can then be pushed to Gerrit.
-
-To squash the commits, use `git rebase -i` to do an interactive rebase. For
-the example above where the last two commits have the same Change-Id,
-this means an interactive rebase for the last two commits should be
-done. For further details about the git rebase command please check
-the link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[Git documentation for rebase].
-
-----
-  $ git rebase -i HEAD~2
-
-  pick ca45e12 one commit
-  squash 13d3812 another commit
-
-  [detached HEAD ab37207] squashed commit
-   1 files changed, 3 insertions(+), 0 deletions(-)
-  Successfully rebased and updated refs/heads/master.
-
-  $ git log
-  commit ab37207d33647685801dba36cb4fd51f3eb73507
-  Author: John Doe <john.doe@example.com>
-  Date:   Thu Dec 16 10:12:54 2010 +0100
-
-      squashed commit
-
-      Change-Id: I93478acac09965af91f03c82e55346214811ac79
-
-  $ git push ssh://JohnDoe@host:29418/myProject HEAD:refs/for/master
-  Counting objects: 5, done.
-  Writing objects: 100% (3/3), 307 bytes, done.
-  Total 3 (delta 0), reused 0 (delta 0)
-  To ssh://JohnDoe@host:29418/myProject
-   * [new branch]      HEAD -> refs/for/master
-----
-
-If it was the intention to create a patch series with multiple
-changes to be reviewed, each commit message should contain the
-Change-Id of the corresponding change in Gerrit.  If a change in
-Gerrit does not exist yet, the Change-Id should be generated (either
-by using a link:cmd-hook-commit-msg.html[commit hook] or by using EGit) or the Change-Id could be
-removed (not recommended since then amending this commit to create
-subsequent patch sets is more error prone). To change the Change-Id
-of an existing commit do an interactive link:http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html[git rebase] and fix the
-affected commit messages.
-
-
-GERRIT
-------
-Part of link:error-messages.html[Gerrit Error Messages]
-
-SEARCHBOX
----------
diff --git a/Documentation/error-upload-denied.txt b/Documentation/error-upload-denied.txt
index 6de94b4..30c5f2d 100644
--- a/Documentation/error-upload-denied.txt
+++ b/Documentation/error-upload-denied.txt
@@ -1,5 +1,4 @@
-Upload denied for project \'...'
-=================================
+= Upload denied for project ...
 
 With this error message Gerrit rejects to push a commit if the
 pushing user has no upload permissions for the project to which the
diff --git a/Documentation/gen_licenses.py b/Documentation/gen_licenses.py
index db3480b..15f470c 100755
--- a/Documentation/gen_licenses.py
+++ b/Documentation/gen_licenses.py
@@ -19,8 +19,8 @@
 
 import argparse
 from collections import defaultdict, deque
+import json
 from os import chdir, path
-import re
 from shutil import copyfileobj
 from subprocess import Popen, PIPE
 from sys import stdout, stderr
@@ -28,7 +28,6 @@
 parser = argparse.ArgumentParser()
 parser.add_argument('--asciidoc', action='store_true')
 parser.add_argument('--partial', action='store_true')
-parser.add_argument('--classpath', action='append')
 parser.add_argument('targets', nargs='+')
 args = parser.parse_args()
 
@@ -38,37 +37,30 @@
   '//lib/bouncycastle:bcprov',
 ]
 
+for target in args.targets:
+  if not target.startswith('//'):
+    print('Target must be absolute: %s' % target, file=stderr)
+
 def parse_graph():
   graph = defaultdict(list)
   while not path.isfile('.buckconfig'):
     chdir('..')
-  # TODO(davido): use passed in classpath from Buck instead
-  p = Popen(
-    ['buck', 'audit', 'classpath', '--dot'] + args.targets,
-    stdout = PIPE)
-  for line in p.stdout:
-    m = re.search(r'"(//.*?)" -> "(//.*?)";', line)
-    if not m:
-      continue
-    target, dep = m.group(1), m.group(2)
-    if args.partial:
-      if dep == '//lib/codemirror:js_minifier':
-        if target == '//lib/codemirror:js':
-          continue
-        if target.startswith('//lib/codemirror:mode_'):
-          continue
-      if target == '//gerrit-gwtui:ui_module' and \
-         dep == '//gerrit-gwtexpui:CSS':
+  query = ' + '.join('deps(%s)' % t for t in args.targets)
+  p = Popen([
+      'buck', 'query', query,
+      '--output-attributes=buck.direct_dependencies'], stdout=PIPE)
+  obj = json.load(p.stdout)
+  for target, attrs in obj.iteritems():
+    for dep in attrs['buck.direct_dependencies']:
+
+      if target in KNOWN_PROVIDED_DEPS:
         continue
 
-    # Dependencies included in provided_deps set are contained in audit
-    # classpath and must be sorted out. That's safe thing to do because
-    # they are not included in the final artifact.
-    if "DO_NOT_DISTRIBUTE" in dep:
-      if not target in KNOWN_PROVIDED_DEPS:
-        print('DO_NOT_DISTRIBUTE license for target: %s' % target, file=stderr)
-        exit(1)
-    else:
+      if (args.partial
+          and dep == '//gerrit-gwtexpui:CSS'
+          and target == '//gerrit-gwtui:ui_module'):
+        continue
+
       graph[target].append(dep)
   r = p.wait()
   if r != 0:
@@ -78,28 +70,39 @@
 graph = parse_graph()
 licenses = defaultdict(set)
 
+do_not_distribute = False
 queue = deque(args.targets)
 while queue:
   target = queue.popleft()
   for dep in graph[target]:
     if not dep.startswith('//lib:LICENSE-'):
       continue
+    if 'DO_NOT_DISTRIBUTE' in dep:
+      do_not_distribute = True
     licenses[dep].add(target)
   queue.extend(graph[target])
+
+if do_not_distribute:
+  print('DO_NOT_DISTRIBUTE license found', file=stderr)
+  for target in args.targets:
+    print('...via %s:' % target)
+    Popen(['buck', 'query',
+           'allpaths(%s, //lib:LICENSE-DO_NOT_DISTRIBUTE)' % target],
+          stdout=stderr).communicate()
+  exit(1)
+
 used = sorted(licenses.keys())
 
 if args.asciidoc:
   print("""\
-Gerrit Code Review - Licenses
-=============================
+= Gerrit Code Review - Licenses
 
 Gerrit open source software is licensed under the <<Apache2_0,Apache
 License 2.0>>.  Executable distributions also include other software
 components that are provided under additional licenses.
 
 [[cryptography]]
-Cryptography Notice
--------------------
+== Cryptography Notice
 
 This distribution includes cryptographic software.  The country
 in which you currently reside may have restrictions on the import,
@@ -134,8 +137,7 @@
 link:http://www.bouncycastle.org/java.html[Bouncy Castle Crypto API]
 to be installed by the end-user.
 
-Licenses
---------
+== Licenses
 """)
 
 for n in used:
@@ -144,27 +146,29 @@
   if args.asciidoc:
     print()
     print('[[%s]]' % name.replace('.', '_'))
-    print(name)
-    print('~' * len(name))
+    print("=== " + name)
     print()
   else:
     print()
     print(name)
-    print('--')
+    print()
+    print('----')
   for d in libs:
     if d.startswith('//lib:') or d.startswith('//lib/'):
       p = d[len('//lib:'):]
     else:
       p = d[d.index(':')+1:].lower()
+    if '__' in p:
+      p = p[:p.index('__')]
     print('* ' + p)
   if args.asciidoc:
     print()
-    print('[[license]]')
-    print('[verse]')
-    print('--')
+    print('[[%s_license]]' % name.replace('.', '_'))
+    print('----')
   with open(n[2:].replace(':', '/')) as fd:
     copyfileobj(fd, stdout)
-  print('--')
+  print()
+  print('----')
 
 if args.asciidoc:
   print("""
diff --git a/Documentation/images/link.png b/Documentation/images/link.png
deleted file mode 100644
index 621443e..0000000
--- a/Documentation/images/link.png
+++ /dev/null
Binary files differ
diff --git a/Documentation/images/user-review-ui-change-screen-not-current.png b/Documentation/images/user-review-ui-change-screen-not-current.png
new file mode 100644
index 0000000..9a87c67
--- /dev/null
+++ b/Documentation/images/user-review-ui-change-screen-not-current.png
Binary files differ
diff --git a/Documentation/index.txt b/Documentation/index.txt
index 63e3be6..f53463c 100644
--- a/Documentation/index.txt
+++ b/Documentation/index.txt
@@ -25,16 +25,15 @@
 
 == Project Management
 . link:project-configuration.html[Project Configuration]
-. link:access-control.html[Access Controls]
 .. link:config-labels.html[Review Labels]
-.. link:config-project-config.html[Access Controls Configuration Format]
+.. link:config-project-config.html[Project Configuration File Format]
+. link:access-control.html[Access Controls]
 . Multi-project management
 .. link:user-submodules.html[Submodules]
 .. link:https://source.android.com/source/using-repo.html[Repo] (external)
 . Prolog rules
 .. link:prolog-cookbook.html[Prolog Cookbook]
 .. link:prolog-change-facts.html[Prolog Facts for Gerrit Changes]
-. link:user-submodules.html[Subscribing to Git Submodules]
 . link:intro-project-owner.html#project-deletion[Project deletion]
 
 == Customization and Integration
@@ -53,6 +52,7 @@
 . link:cmd-index.html[Command Line Tools]
 . link:config-plugins.html#replication[Replication]
 . link:config-plugins.html[Plugins]
+. link:metrics.html[Metrics]
 . link:config-reverseproxy.html[Reverse Proxy]
 . link:config-auto-site-initialization.html[Automatic Site Initialization on Startup]
 . link:pgm-index.html[Server Side Administrative Tools]
@@ -68,12 +68,14 @@
 .. link:dev-build-plugins.html[Building Gerrit plugins]
 .. link:js-api.html[JavaScript Plugin API]
 .. link:config-validation.html[Validation Interfaces]
+.. link:dev-stars.html[Starring Changes]
 . link:dev-design.html[System Design]
 . link:i18n-readme.html[i18n Support]
 
 == Maintainer
-. link:dev-release.html[Developer Release]
-. link:dev-release-subproject.html[Developer Subproject Release]
+. link:dev-release.html[Making a Gerrit Release]
+. link:dev-release-subproject.html[Making a Release of a Gerrit Subproject]
+. link:dev-release-jgit.html[Making a Release of JGit]
 
 == Resources
 * link:licenses.html[Licenses and Notices]
@@ -83,5 +85,9 @@
 * link:https://gerrit.googlesource.com/gerrit[Source Code]
 * link:https://www.gerritcodereview.com/about.md[A History of Gerrit Code Review]
 
+GERRIT
+------
+Part of link:https://www.gerritcodereview.com/[Gerrit Code Review]
+
 SEARCHBOX
 ---------
diff --git a/Documentation/install.txt b/Documentation/install.txt
index 3f7d1c1..e3fb28d 100644
--- a/Documentation/install.txt
+++ b/Documentation/install.txt
@@ -17,7 +17,8 @@
 Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files_
 from Oracle and installing them into your JRE.
 
-NOTE: Installing JCE extensions is optional and export restrictions may apply.
+[NOTE]
+Installing JCE extensions is optional and export restrictions may apply.
 
 . Download the unlimited strength JCE policy files.
 +
@@ -82,7 +83,8 @@
   java -jar gerrit.war init -d /path/to/your/gerrit_application_directory
 ----
 
-'Please note:' If you choose a location where your new user doesn't
+[NOTE]
+If you choose a location where your new user doesn't
 have any privileges, you may have to manually create the directory first and
 then give ownership of that location to the `'gerrit2'` user.
 
@@ -137,11 +139,11 @@
 To control the Gerrit Code Review daemon that is running in the
 background, use the rc.d style start script created by 'init':
 
-====
+----
   review_site/bin/gerrit.sh start
   review_site/bin/gerrit.sh stop
   review_site/bin/gerrit.sh restart
-====
+----
 
 ('Optional') Configure the daemon to automatically start and stop
 with the operating system.
@@ -149,18 +151,18 @@
 Uncomment the following 3 lines in the `'$site_path/bin/gerrit.sh'`
 script:
 
-====
+----
  chkconfig: 3 99 99
  description: Gerrit Code Review
  processname: gerrit
-====
+----
 
 Then link the `gerrit.sh` script into `rc3.d`:
 
-====
+----
   sudo ln -snf `pwd`/review_site/bin/gerrit.sh /etc/init.d/gerrit
   sudo ln -snf /etc/init.d/gerrit /etc/rc3.d/S90gerrit
-====
+----
 
 ('Optional') To enable autocompletion of the gerrit.sh commands, install
 autocompletion from the `/contrib/bash_completion` script.  Refer to the
diff --git a/Documentation/intro-project-owner.txt b/Documentation/intro-project-owner.txt
index dfffe57..7a724f7 100644
--- a/Documentation/intro-project-owner.txt
+++ b/Documentation/intro-project-owner.txt
@@ -69,11 +69,11 @@
 cloned the repository you can do this by executing the following
 commands:
 
-====
+----
   $ git fetch origin refs/meta/config:config
   $ git checkout config
   $ git log project.config
-====
+----
 
 Non project owners may still edit the access rights and propose the
 modifications to the project owners by clicking on the `Save for
@@ -519,11 +519,11 @@
 to an issue in an issue tracker system. For example, to link the ID
 from the `Bug` footer to Jira the following configuration can be used:
 
-====
+----
   [commentlink "myjira"]
     match = ([Bb][Uu][Gg]:\\s+)(\\S+)
     link =  https://myjira/browse/$2
-====
+----
 
 [[reviewers]]
 == Reviewers
@@ -594,11 +594,11 @@
 The project-specific download commands must be configured in the
 `project.config` file in the `refs/meta/config` branch of the project:
 +
-====
+----
   [plugin "project-download-commands"]
     Build = git fetch ${url} ${ref} && git checkout FETCH_HEAD && buck build ${project}
     Update = git fetch ${url} ${ref} && git checkout FETCH_HEAD && git submodule update
-====
+----
 +
 Project-specific download commands that are defined on a parent project
 are inherited by the child projects. A child project can overwrite an
@@ -652,7 +652,7 @@
 How to develop a Gerrit plugin is described in the link:dev-plugins.html[
 Plugin Development] section.
 
-[[prject-lifecycle]]
+[[project-lifecycle]]
 == Project Lifecycle
 
 [[project-creation]]
@@ -705,9 +705,9 @@
 commits (the author information that records who was writing the code
 stays intact; signed tags will lose their signature):
 
-====
+----
   $ git filter-branch --tag-name-filter cat --env-filter 'GIT_COMMITTER_NAME="John Doe"; GIT_COMMITTER_EMAIL="john.doe@example.com";' -- --all
-====
+----
 
 If a link:config-gerrit.html#receive.maxObjectSizeLimit[max object size
 limit] is configured on the server you may need to remove large objects
@@ -715,20 +715,22 @@
 the history of your project you can use the `reposize.sh` script which
 you can download from Gerrit:
 
+----
   $ curl -Lo reposize.sh http://review.example.com:8080/tools/scripts/reposize.sh
 
 or
 
   $ scp -p -P 29418 john.doe@review.example.com:scripts/reposize.sh .
+----
 
 You can then use the
 link:https://www.kernel.org/pub/software/scm/git/docs/git-filter-branch.html[
 git filter-branch] command to remove the large objects from the history
 of all branches:
 
-====
+----
   $ git filter-branch -f --index-filter 'git rm --cached --ignore-unmatch path/to/large-file.jar' -- --all
-====
+----
 
 Since this command rewrites all commits in the repository it's a good
 idea to create a fresh clone from this rewritten repository before
diff --git a/Documentation/intro-user.txt b/Documentation/intro-user.txt
index b9bdad0..9bf6842 100644
--- a/Documentation/intro-user.txt
+++ b/Documentation/intro-user.txt
@@ -583,22 +583,6 @@
 
 The following preferences can be configured:
 
-- [[show-site-header]]`Show Site Header`:
-+
-Whether the site header should be shown.
-
-- [[use-flash]]`Use Flash Clipboard Widget`:
-+
-Whether the Flash clipboard widget should be used. If enabled Gerrit
-offers a copy-to-clipboard icon next to IDs and commands that need to
-be copied frequently, such as the Change-Ids, commit IDs and download
-commands.
-
-- [[cc-me]]`CC Me On Comments I Write`:
-+
-Whether you get notified by email as CC on comments that you write
-yourself.
-
 - [[review-category]]`Display In Review Category`:
 +
 This setting controls how the values of the review labels in change
@@ -607,7 +591,7 @@
 ** `None`:
 +
 For each review label only the voting value is shown. Approvals are
-rendered as a green check mark icon, vetos as a red X icon.
+rendered as a green check mark icon, vetoes as a red X icon.
 +
 ** `Show Name`:
 +
@@ -638,6 +622,32 @@
 +
 The format that should be used to render dates and timestamps.
 
+- [[email-notifications]]`Email Notifications`:
++
+This setting controls the email notifications.
++
+** `Enabled`:
++
+Email notifications are enabled.
++
+** [[cc-me]]`CC Me On Comments I Write`:
++
+Email notifications are enabled and you get notified by email as CC
+on comments that you write yourself.
++
+** `Disabled`:
++
+Email notifications are disabled.
+
+- [[diff-view]]`Diff View`:
++
+Whether the Side-by-Side diff view or the Unified diff view should be
+shown when clicking on a file path in the change screen.
+
+- [[show-site-header]]`Show Site Header / Footer`:
++
+Whether the site header and footer should be shown.
+
 - [[relative-dates]]`Show Relative Dates In Changes Table`:
 +
 Whether timestamps in change lists and dashboards should be shown as
@@ -660,10 +670,20 @@
 Whether common path prefixes in the file list on the change screen
 should be link:user-review-ui.html#repeating-path-segments[grayed out].
 
-- [[diff-view]]`Diff View`:
+- [[inline-signed-off]]`Insert Signed-off-by Footer For Inline Edit Changes`:
 +
-Whether the Side-by-Side diff view or the Unified diff view should be
-shown when clicking on a file path in the change screen.
+Whether a `Signed-off-by` footer should be automatically inserted into
+changes that are created from the web UI (e.g. by the `Create Change`
+and `Edit Config` buttons on the project screen, and the `Follow-Up`
+button on the change screen).
+
+- [[use-flash]]`Use Flash Clipboard Widget`:
++
+Whether the Flash clipboard widget should be used. If enabled and the Flash
+plugin is available, Gerrit offers a copy-to-clipboard icon next to IDs and
+commands that need to be copied frequently, such as the Change-Ids, commit IDs
+and download commands. Note that this option is only shown if the Flash plugin
+is available and the JavaScript Clipboard API is unavailable.
 
 [[my-menu]]
 In addition it is possible to customize the menu entries of the `My`
diff --git a/Documentation/js-api.txt b/Documentation/js-api.txt
index 03ff5a5..8c9950e 100644
--- a/Documentation/js-api.txt
+++ b/Documentation/js-api.txt
@@ -176,6 +176,13 @@
   function must return true to allow the operation to continue, or
   false to prevent it.
 
+* `comment`: Invoked when a DOM element that represents a comment is
+  created. This DOM element is passed as argument. This DOM element
+  contains nested elements that Gerrit uses to format the comment. The
+  DOM structure may differ between comment types such as inline
+  comments, file-level comments and summary comments, and it may change
+  with new Gerrit versions.
+
 [[self_onAction]]
 === self.onAction()
 Register a JavaScript callback to be invoked when the user clicks
@@ -219,6 +226,50 @@
 * callback: JavaScript function to invoke when the user navigates to
   the screen. The function will be passed a link:#ScreenContext[screen context].
 
+[[self_settingsScreen]]
+=== self.settingsScreen()
+Register a JavaScript callback to be invoked when the user navigates
+to an extension settings screen provided by the plugin. Extension settings
+screens are automatically linked from the settings menu under the given
+menu entry.
+The callback can populate the DOM with the screen's contents.
+
+.Signature
+[source,javascript]
+----
+self.settingsScreen(path, menu, callback);
+----
+
+* path: URL path to identify the settings screen.
+
+* menu: The name of the menu entry in the settings menu that should
+  link to the settings screen.
+
+* callback: JavaScript function to invoke when the user navigates to
+  the settings screen. The function will be passed a
+  link:#SettingsScreenContext[settings screen context].
+
+[[self_panel]]
+=== self.panel()
+Register a JavaScript callback to be invoked when a screen with the
+given extension point is loaded.
+The callback can populate the DOM with the panel's contents.
+
+.Signature
+[source,javascript]
+----
+self.panel(extensionpoint, callback);
+----
+
+* extensionpoint: The name of the extension point that marks the
+  position where the panel is added to an existing screen. The
+  available extension points are described in the
+  link:dev-plugins.html#panels[plugin development documentation].
+
+* callback: JavaScript function to invoke when a screen with the
+  extension point is loaded. The function will be passed a
+  link:#PanelContext[panel context].
+
 [[self_url]]
 === self.url()
 Returns a URL within the plugin's URL space. If invoked with no
@@ -562,6 +613,86 @@
 Destroy the currently visible screen and display the plugin's screen.
 This method must be called after adding content to `screen.body`.
 
+[[SettingsScreenContext]]
+== Settings Screen Context
+A new settings screen context is passed to the `settingsScreen` callback
+function each time the user navigates to a matching URL.
+
+[[settingsScreen_body]]
+=== settingsScreen.body
+Empty HTML `<div>` node the plugin should add its content to.  The
+node is already attached to the document, but is invisible.  Plugins
+must call `settingsScreen.show()` to display the DOM node.  Deferred
+display allows an implementor to partially populate the DOM, make
+remote HTTP requests, finish populating when the callbacks arrive, and
+only then make the view visible to the user.
+
+[[settingsScreen_onUnload]]
+=== settingsScreen.onUnload()
+Configures an optional callback to be invoked just before the screen
+is deleted from the browser DOM.  Plugins can use this callback to
+remove event listeners from DOM nodes, preventing memory leaks.
+
+.Signature
+[source,javascript]
+----
+settingsScreen.onUnload(callback)
+----
+
+* callback: JavaScript function to be invoked just before the
+  `settingsScreen.body` DOM element is removed from the browser DOM.
+  This event happens when the user navigates to another screen.
+
+[[settingsScreen.setTitle]]
+=== settingsScreen.setTitle()
+Sets the heading text to be displayed when the screen is visible.
+This is presented in a large bold font below the menus, but above the
+content in `settingsScreen.body`. Setting the title also sets the
+window title to the same string, if it has not already been set.
+
+.Signature
+[source,javascript]
+----
+settingsScreen.setPageTitle(titleText)
+----
+
+[[settingsScreen.setWindowTitle]]
+=== settingsScreen.setWindowTitle()
+Sets the text to be displayed in the browser's title bar when the
+screen is visible.  Plugins should always prefer this method over
+trying to set `window.title` directly.  The window title defaults to
+the title given to `setTitle`.
+
+.Signature
+[source,javascript]
+----
+settingsScreen.setWindowTitle(titleText)
+----
+
+[[settingsScreen_show]]
+=== settingsScreen.show()
+Destroy the currently visible screen and display the plugin's screen.
+This method must be called after adding content to
+`settingsScreen.body`.
+
+[[PanelContext]]
+== Panel Context
+A new panel context is passed to the `panel` callback function each
+time a screen with the given extension point is loaded.
+
+[[panel_body]]
+=== panel.body
+Empty HTML `<div>` node the plugin should add the panel content to.
+The node is already attached to the document.
+
+[[PanelProperties]]
+=== Properties
+
+The extension panel parameters that are described in the
+link:dev-plugins.html#panels[plugin development documentation] are
+contained in the context as properties. Which properties are available
+depends on the extension point.
+
 [[Gerrit]]
 == Gerrit
 
diff --git a/Documentation/json.txt b/Documentation/json.txt
index 32fa472..ef40aee 100644
--- a/Documentation/json.txt
+++ b/Documentation/json.txt
@@ -116,6 +116,8 @@
 
   TRIVIAL_REBASE;; Conflict-free merge between the new parent and the prior patch set.
 
+  MERGE_FIRST_PARENT_UPDATE;; Conflict-free change of first (left) parent of a merge commit.
+
   NO_CODE_CHANGE;; No code changed; same tree and same parent tree.
 
   NO_CHANGE;; No changes; same commit message, same tree and same parent tree.
@@ -140,6 +142,8 @@
 
 value:: Value assigned by the approval, usually a numerical score.
 
+oldValue:: The previous approval score, only present if the value changed as a result of this event.
+
 grantedOn:: Time in seconds since the UNIX epoch when this approval
 was added or last updated.
 
diff --git a/Documentation/license.defs b/Documentation/license.defs
new file mode 100644
index 0000000..42dd3eb
--- /dev/null
+++ b/Documentation/license.defs
@@ -0,0 +1,29 @@
+def genlicenses(
+    name,
+    out,
+    opts = [],
+    java_deps = [],
+    non_java_deps = [],
+    visibility = []):
+  cmd = ['$(exe :gen_licenses)']
+  cmd.extend(opts)
+  cmd.append('>$OUT')
+  cmd.extend(java_deps)
+  cmd.extend(non_java_deps)
+
+  # Must use $(classpath) for Java deps, since transitive dependencies are not
+  # first-order dependencies of the output jar, so changes would not cause
+  # invalidation of the build cache key for the genrule.
+  cmd.extend('; true $(classpath %s)' % d for d in java_deps)
+
+  # Must use $(location) for non-Java deps, since $(classpath) will fail with an
+  # error. This is ok, because transitive dependencies are included in the
+  # output artifacts for everything _except_ Java libraries.
+  cmd.extend('; true $(location %s)' % d for d in non_java_deps)
+
+  genrule(
+    name = name,
+    out = out,
+    cmd = ' '.join(cmd),
+    visibility = visibility,
+  )
diff --git a/Documentation/metrics.txt b/Documentation/metrics.txt
new file mode 100644
index 0000000..1270971
--- /dev/null
+++ b/Documentation/metrics.txt
@@ -0,0 +1,110 @@
+= Gerrit Code Review - Metrics
+
+Metrics about Gerrit's internal state can be sent to external monitoring systems
+via plugins. See the link:dev-plugins.html#metrics[plugin documentation] for
+details of plugin implementations.
+
+== Metrics
+
+The following metrics are reported.
+
+=== General
+
+* `build/label`: Version of Gerrit server software.
+* `events`: Triggered events.
+
+=== Process
+
+* `proc/birth_timestamp`: Time at which the Gerrit process started.
+* `proc/uptime`: Uptime of the Gerrit process.
+* `proc/cpu/usage`: CPU time used by the Gerrit process.
+* `proc/num_open_fds`: Number of open file descriptors.
+* `proc/jvm/memory/heap_committed`: Amount of memory guaranteed for user objects.
+* `proc/jvm/memory/heap_used`: Amount of memory holding user objects.
+* `proc/jvm/memory/non_heap_committed`: Amount of memory guaranteed for classes,
+etc.
+* `proc/jvm/memory/non_heap_used`: Amount of memory holding classes, etc.
+* `proc/jvm/memory/object_pending_finalization_count`: Approximate number of
+objects needing finalization.
+* `proc/jvm/gc/count`: Number of GCs.
+* `proc/jvm/gc/time`: Approximate accumulated GC elapsed time.
+* `proc/jvm/thread/num_live`: Current live thread count.
+
+=== Caches
+
+* `caches/memory_cached`: Memory entries.
+* `caches/memory_hit_ratio`: Memory hit ratio.
+* `caches/memory_eviction_count`: Memory eviction count.
+* `caches/disk_cached`: Disk entries used by persistent cache.
+* `caches/disk_hit_ratio`: Disk hit ratio for persistent cache.
+
+=== HTTP
+
+* `http/server/error_count`: Rate of REST API error responses.
+* `http/server/success_count`: Rate of REST API success responses.
+* `http/server/rest_api/count`: Rate of REST API calls by view.
+* `http/server/rest_api/error_count`: Rate of REST API calls by view.
+* `http/server/rest_api/server_latency`: REST API call latency by view.
+* `http/server/rest_api/response_bytes`: Size of REST API response on network
+(may be gzip compressed) by view.
+
+=== Query
+
+* `query/query_latency`: Successful query latency, accumulated over the life
+of the process.
+
+=== SSH sessions
+
+* `sshd/sessions/connected`: Number of currently connected SSH sessions.
+* `sshd/sessions/created`: Rate of new SSH sessions.
+* `sshd/sessions/authentication_failures`: Rate of SSH authentication failures.
+
+=== SQL connections
+
+* `sql/connection_pool/connections`: SQL database connections.
+
+=== JGit
+
+* `jgit/block_cache/cache_used`: Bytes of memory retained in JGit block cache.
+* `jgit/block_cache/open_files`: File handles held open by JGit block cache.
+
+=== Git
+
+* `git/upload-pack/request_count`: Total number of git-upload-pack requests.
+* `git/upload-pack/phase_counting`: Time spent in the 'Counting...' phase.
+* `git/upload-pack/phase_compressing`: Time spent in the 'Compressing...' phase.
+* `git/upload-pack/phase_writing`: Time spent transferring bytes to client.
+* `git/upload-pack/pack_bytes`: Distribution of sizes of packs sent to clients.
+
+=== NoteDb
+
+* `notedb/update_latency`: NoteDb update latency by table.
+* `notedb/stage_update_latency`: Latency for staging updates to NoteDb by table.
+* `notedb/read_latency`: NoteDb read latency by table.
+* `notedb/parse_latency`: NoteDb parse latency by table.
+* `notedb/auto_rebuild_latency`: NoteDb auto-rebuilding latency by table.
+* `notedb/auto_rebuild_failure_count`: NoteDb auto-rebuilding attempts that
+failed by table.
+
+=== Reviewer Suggestion
+
+* `reviewer_suggestion/query_accounts`: Latency for querying accounts for
+reviewer suggestion.
+* `reviewer_suggestion/query_groups`: Latency for querying groups for reviewer
+suggestion.
+
+=== Replication Plugin
+
+* `plugins/replication/replication_latency`: Time spent pushing to remote
+destination.
+* `plugins/replication/replication_delay`: Time spent waiting before pushing to
+remote destination.
+* `plugins/replication/replication_retries`: Number of retries when pushing to
+remote destination.
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------
diff --git a/Documentation/pgm-LocalUsernamesToLowerCase.txt b/Documentation/pgm-LocalUsernamesToLowerCase.txt
index 09651c2..1136ced 100644
--- a/Documentation/pgm-LocalUsernamesToLowerCase.txt
+++ b/Documentation/pgm-LocalUsernamesToLowerCase.txt
@@ -5,8 +5,11 @@
 account to lower case
 
 == SYNOPSIS
+[verse]
 --
-'java' -jar gerrit.war 'LocalUsernamesToLowerCase' -d <SITE_PATH>
+_java_ -jar gerrit.war _LocalUsernamesToLowerCase
+  -d <SITE_PATH>
+  [--threads]
 --
 
 == DESCRIPTION
@@ -48,9 +51,9 @@
 == EXAMPLES
 To convert the local username of every account to lower case:
 
-====
+----
 	$ java -jar gerrit.war LocalUsernamesToLowerCase -d site_path
-====
+----
 
 == SEE ALSO
 
diff --git a/Documentation/pgm-MigrateAccountPatchReviewDb.txt b/Documentation/pgm-MigrateAccountPatchReviewDb.txt
new file mode 100644
index 0000000..5718a8a
--- /dev/null
+++ b/Documentation/pgm-MigrateAccountPatchReviewDb.txt
@@ -0,0 +1,66 @@
+= MigrateAccountPatchReviewDb
+
+== NAME
+MigrateAccountPatchReviewDb - Migrates AccountPatchReviewDb from one database
+backend to another.
+
+== SYNOPSIS
+[verse]
+--
+_java_ -jar gerrit.war MigrateAccountPatchReviewDb
+  -d <SITE_PATH>
+  [--sourceUrl] [--chunkSize]
+--
+
+== DESCRIPTION
+Migrates AccountPatchReviewDb from one database backend to another. The
+AccountPatchReviewDb is a database used to store the user file reviewed flags.
+
+This command is only intended to be run if the configuration parameter
+link:config-gerrit.html#accountPatchReviewDb.url[accountPatchReviewDb.url]
+is set or changed.
+
+To migrate AccountPatchReviewDb:
+
+* Stop Gerrit
+* Configure new value for link:config-gerrit.html#accountPatchReviewDb.url[accountPatchReviewDb.url]
+* Migrate data using this command
+* Start Gerrit
+
+== OPTIONS
+
+-d::
+--site-path::
+	Location of the `gerrit.config` file, and all other per-site
+	configuration data, supporting libraries and log files.
+
+--sourceUrl::
+	Url of source database. Only need to be specified if the source is not H2.
+
+--chunkSize::
+	Chunk size of fetching from source and pushing to target on each time.
+	Defaults to 100000.
+
+== CONTEXT
+This command can only be run on a server which has direct
+connectivity to the database.
+
+== EXAMPLES
+To migrate from H2 to the database specified by
+link:config-gerrit.html#accountPatchReviewDb.url[accountPatchReviewDb.url]
+in gerrit.config:
+
+----
+	$ java -jar gerrit.war MigrateAccountPatchReviewDb -d site_path
+----
+
+== SEE ALSO
+
+* Configuration parameter link:config-gerrit.html#accountPatchReviewDb.url[accountPatchReviewDb.url]
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------
diff --git a/Documentation/pgm-SwitchSecureStore.txt b/Documentation/pgm-SwitchSecureStore.txt
index f9b2aa4..47de1be 100644
--- a/Documentation/pgm-SwitchSecureStore.txt
+++ b/Documentation/pgm-SwitchSecureStore.txt
@@ -4,8 +4,10 @@
 SwitchSecureStore - Changes the currently used SecureStore implementation
 
 == SYNOPSIS
+[verse]
 --
-'java' -jar gerrit.war 'SwitchSecureStore' [<OPTIONS>]
+_java_ -jar gerrit.war _SwitchSecureStore_
+  [--new-secure-store-lib]
 --
 
 == DESCRIPTION
diff --git a/Documentation/pgm-daemon.txt b/Documentation/pgm-daemon.txt
index bcf2b1b..76a26e1 100644
--- a/Documentation/pgm-daemon.txt
+++ b/Documentation/pgm-daemon.txt
@@ -4,16 +4,17 @@
 daemon - Gerrit network server
 
 == SYNOPSIS
+[verse]
 --
-'java' -jar gerrit.war 'daemon'
-	-d <SITE_PATH>
-	[--enable-httpd | --disable-httpd]
-	[--enable-sshd | --disable-sshd]
-	[--console-log]
-	[--slave]
-	[--headless]
-	[--init]
-	[-s]
+_java_ -jar gerrit.war _daemon_
+  -d <SITE_PATH>
+  [--enable-httpd | --disable-httpd]
+  [--enable-sshd | --disable-sshd]
+  [--console-log]
+  [--slave]
+  [--headless]
+  [--init]
+  [-s]
 --
 
 == DESCRIPTION
diff --git a/Documentation/pgm-gsql.txt b/Documentation/pgm-gsql.txt
index ba40b26..4986522 100644
--- a/Documentation/pgm-gsql.txt
+++ b/Documentation/pgm-gsql.txt
@@ -4,8 +4,10 @@
 gsql - Administrative interface to idle database
 
 == SYNOPSIS
+[verse]
 --
-'java' -jar gerrit.war 'gsql' -d <SITE_PATH>
+_java_ -jar gerrit.war _gsql_
+  -d <SITE_PATH>
 --
 
 == DESCRIPTION
@@ -32,7 +34,7 @@
 == EXAMPLES
 To manually correct a user's SSH user name:
 
-====
+----
 	$ java -jar gerrit.war gsql
 	Welcome to Gerrit Code Review v2.0.25
 	(PostgreSQL 8.3.8)
@@ -43,7 +45,7 @@
 	UPDATE 1; 1 ms
 	gerrit> \q
 	Bye
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/pgm-index.txt b/Documentation/pgm-index.txt
index bf6dc57..d61cc0b 100644
--- a/Documentation/pgm-index.txt
+++ b/Documentation/pgm-index.txt
@@ -33,11 +33,17 @@
 version::
 	Display the release version of Gerrit Code Review.
 
+link:pgm-passwd.html[passwd]::
+	Set or reset password in secure.config.
+
 === Transition Utilities
 
 link:pgm-LocalUsernamesToLowerCase.html[LocalUsernamesToLowerCase]::
 	Convert the local username of every account to lower case.
 
+link:pgm-MigrateAccountPatchReviewDb.html[MigrateAccountPatchReviewDb]::
+	Migrates AccountPatchReviewDb from one database backend to another.
+
 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/pgm-init.txt b/Documentation/pgm-init.txt
index 6aa3a74..9a16cdf 100644
--- a/Documentation/pgm-init.txt
+++ b/Documentation/pgm-init.txt
@@ -1,17 +1,25 @@
 = init
 
 == NAME
-init - Initialize a new Gerrit server installation
+init - Initialize a new Gerrit server installation or upgrade an existing
+installation.
 
 == SYNOPSIS
+[verse]
 --
-'java' -jar gerrit.war 'init'
-	-d <SITE_PATH>
-	[--batch]
-	[--no-auto-start]
-	[--list-plugins]
-	[--install-plugin=<PLUGIN_NAME>]
-        [--dev]
+_java_ -jar gerrit.war _init_
+  -d <SITE_PATH>
+  [--batch]
+  [--delete-caches]
+  [--no-auto-start]
+  [--skip-plugins]
+  [--list-plugins]
+  [--install-plugin=<PLUGIN_NAME>]
+  [--install-all-plugins]
+  [--secure-store-lib]
+  [--dev]
+  [--skip-all-downloads]
+  [--skip-download=<LIBRARY_NAME>]
 --
 
 == DESCRIPTION
@@ -19,19 +27,25 @@
 for some basic setup prior to writing default configuration files
 into a newly created `$site_path`.
 
-If run in an existing `$site_path`, init will upgrade some resources
-as necessary.
+If run in an existing `$site_path`, init upgrades existing resources
+(e.g. DB schema, plugins) as necessary.
 
 == OPTIONS
+-b::
 --batch::
-	Run in batch mode, skipping interactive prompts.  Reasonable
-	configuration defaults are chosen based on the whims of
-	the Gerrit developers.
+	Run in batch mode, skipping interactive prompts. For a fresh
+	install, reasonable configuration defaults are chosen based
+	on the whims of the Gerrit developers. On upgrades, the existing
+	settings in `gerrit.config` are respected.
 +
 If during a schema migration unused objects (e.g. tables, columns)
-are detected they are *not* automatically dropped, but only a list of
-SQL statements to drop these objects is provided. To drop the unused
-objects these SQL statements have to be executed manually.
+are detected, they are *not* automatically dropped; a list of SQL
+statements to drop these objects is provided. To drop the unused
+objects these SQL statements must be executed manually.
+
+--delete-caches::
+	Force deletion of all persistent cache files. Note that
+	re-creation of these caches may be expensive.
 
 --no-auto-start::
 	Don't automatically start the daemon after initializing a
@@ -41,21 +55,50 @@
 
 -d::
 --site-path::
-	Location of the gerrit.config file, and all other per-site
+	Location of the `gerrit.config` file, and all other per-site
 	configuration data, supporting libraries and log files.
 
+--skip-plugins::
+	Entirely skip installation and initialization of plugins. This option
+	is needed when initializing a gerrit site without an archive. That
+	happens when running gerrit acceptance or integration tests in a
+	debugger, using classes. Supplying this option leads to ignoring the
+	`--install-plugin` and `--install-all-plugins` options, if supplied as well.
+
 --list-plugins::
 	Print names of plugins that can be installed during init process.
 
+--install-all-plugins::
+	Automatically install all plugins from gerrit.war without asking.
+	This option also works in batch mode. This option cannot be supplied
+	alongside `--install-plugin`.
+
+--secure-store-lib::
+	Path to the jar providing the chosen
+	link:dev-plugins.html#secure-store[SecureStore] implementation class.
+	This option is used in the same way as the `--new-secure-store-lib` option
+	documented in link:pgm-SwitchSecureStore.html[SwitchSecureStore].
+
 --install-plugin::
 	Automatically install plugin with given name without asking.
-	This option may be supplied more than once to install multiple
-	plugins.
+	This option also works in batch mode. This option may be supplied
+	more than once to install multiple plugins. This option cannot be
+	supplied alongside `--install-all-plugins`.
 
 --dev::
 	Install in developer mode. Default configuration settings are
 	chosen to run the Gerrit server as a developer.
 
+--skip-all-downloads::
+	Do not automatically download and install required libraries. The
+	administrator must manually install the required libraries in the `lib/`
+	folder.
+
+--skip-download::
+	Do not automatically download and install the library with the given name.
+	The administrator must manually install the required library in the `lib/`
+	folder.
+
 == CONTEXT
 This command can only be run on a server which has direct
 connectivity to the metadata database, and local access to the
diff --git a/Documentation/pgm-passwd.txt b/Documentation/pgm-passwd.txt
new file mode 100644
index 0000000..133fb03
--- /dev/null
+++ b/Documentation/pgm-passwd.txt
@@ -0,0 +1,49 @@
+= passwd
+
+== NAME
+passwd - Set or reset password in secure.config.
+
+== SYNOPSIS
+[verse]
+--
+_java_ -jar gerrit.war _passwd_
+  -d <SITE_PATH>
+  <SECTION.KEY>
+  [PASSWORD]
+
+--
+
+== DESCRIPTION
+Set or reset password in an existing Gerrit server installation,
+interactively prompting for a new password or using the one
+provided in the command line argument.
+
+== OPTIONS
+
+-d::
+--site-path::
+	Location of the `gerrit.config` file, and all other per-site
+	configuration data, supporting libraries and log files.
+
+== ARGUMENTS
+
+SECTION.KEY::
+	Section and key in the `secure.config` file for setting or editing the
+	password value.
+
+PASSWORD::
+	New password to set in `secure.config` associated to the section and key.
+	When specified as argument, automatically implies batch mode and the command
+	would not ask anything interactively.
+
+== CONTEXT
+
+This utility is typically useful when a secure store is configured
+to encrypt password values and thus editing the file manually is not an option.
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------
diff --git a/Documentation/pgm-prolog-shell.txt b/Documentation/pgm-prolog-shell.txt
index 9861310..aee5799 100644
--- a/Documentation/pgm-prolog-shell.txt
+++ b/Documentation/pgm-prolog-shell.txt
@@ -4,8 +4,10 @@
 prolog-shell - Simple interactive Prolog interpreter
 
 == SYNOPSIS
+[verse]
 --
-'java' -jar gerrit.war 'prolog-shell' [-s FILE.pl ...]
+_java_ -jar gerrit.war _prolog-shell_
+  [-s FILE.pl ...]
 --
 
 == DESCRIPTION
@@ -22,7 +24,7 @@
 == EXAMPLES
 Define a simple predicate and test it:
 
-====
+----
 	$ cat >simple.pl
 	food(apple).
 	food(orange).
@@ -45,7 +47,7 @@
 
 	no
 	| ?-
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/pgm-reindex.txt b/Documentation/pgm-reindex.txt
index bf09e0c..e13d518 100644
--- a/Documentation/pgm-reindex.txt
+++ b/Documentation/pgm-reindex.txt
@@ -4,8 +4,14 @@
 reindex - Rebuild the secondary index
 
 == SYNOPSIS
+[verse]
 --
-'java' -jar gerrit.war 'reindex' [<OPTIONS>]
+_java_ -jar gerrit.war _reindex_
+  [--threads]
+  [--changes-schema-version]
+  [--verbose]
+  [--list]
+  [--index]
 --
 
 == DESCRIPTION
@@ -15,15 +21,19 @@
 --threads::
 	Number of threads to use for indexing.
 
---schema-version::
+--changes-schema-version::
 	Schema version to reindex; default is most recent version.
 
---output::
-	Prefix for output; path for local disk index, or prefix for remote index.
-
 --verbose::
 	Output debug information for each change.
 
+--list::
+	List available index names.
+
+--index::
+	Reindex only index with given name. This option can be supplied
+	more than once to reindex multiple indices.
+
 == CONTEXT
 The secondary index must be enabled. See
 link:config-gerrit.html#index.type[index.type].
diff --git a/Documentation/pgm-rulec.txt b/Documentation/pgm-rulec.txt
index 3236c38..1b50812 100644
--- a/Documentation/pgm-rulec.txt
+++ b/Documentation/pgm-rulec.txt
@@ -4,8 +4,12 @@
 rulec - Compile project-specific Prolog rules to JARs
 
 == SYNOPSIS
+[verse]
 --
-'java' -jar gerrit.war 'rulec' -d <SITE_PATH> [--all | <PROJECT>...]
+_java_ -jar gerrit.war _rulec_
+  -d <SITE_PATH>
+  [--quiet]
+  [--all | <PROJECT>...]
 --
 
 == DESCRIPTION
@@ -39,9 +43,9 @@
 == EXAMPLES
 To compile a rule JAR file for test/project:
 
-====
+----
 	$ java -jar gerrit.war rulec -d site_path test/project
-====
+----
 
 GERRIT
 ------
diff --git a/Documentation/project-configuration.txt b/Documentation/project-configuration.txt
index 6d7c6d0..d71d19a 100644
--- a/Documentation/project-configuration.txt
+++ b/Documentation/project-configuration.txt
@@ -22,9 +22,9 @@
 
 . Create a Git repository under `gerrit.basePath`:
 +
-====
+----
   git --git-dir=$base_path/new/project.git init
-====
+----
 +
 [TIP]
 By tradition the repository directory name should have a `.git`
@@ -33,17 +33,17 @@
 To also make this repository available over the anonymous git://
 protocol, don't forget to create a `git-daemon-export-ok` file:
 +
-====
+----
   touch $base_path/new/project.git/git-daemon-export-ok
-====
+----
 
 . Register Project
 +
 Either restart the server, or flush the `project_list` cache:
 +
-====
+----
   ssh -p 29418 localhost gerrit flush-caches --cache project_list
-====
+----
 
 [[project_options]]
 == Project Options
@@ -53,7 +53,9 @@
 
 The method Gerrit uses to submit a change to a project can be
 modified by any project owner through the project console, `Projects` >
-`List` > my/project.  The following methods are supported:
+`List` > my/project. In general, a submitted change is only merged if all
+its dependencies are also submitted, with exceptions documented below.
+The following submit types are supported:
 
 [[fast_forward_only]]
 * Fast Forward Only
@@ -96,10 +98,12 @@
 is also set to the submitter, while the author header retains the
 original patch set author.
 +
-Note that Gerrit ignores patch set dependencies when operating in
-cherry-pick mode. Submitters must remember to submit changes in
-the right order since inter-change dependencies will not be
-enforced for them.
+Note that Gerrit ignores dependencies between changes when using this
+submit type unless
+link:config-gerrit.html#change.submitWholeTopic[`change.submitWholeTopic`]
+is enabled and depending changes share the same topic. So generally
+submitters must remember to submit changes in the right order when using this
+submit type.
 
 [[rebase_if_necessary]]
 * Rebase If Necessary
@@ -258,9 +262,9 @@
   REST endpoint
 - by using a git client to force push nothing to an existing branch
 +
-====
+----
   $ git push --force origin :refs/heads/<branch-to-delete>
-====
+----
 
 To be able to delete branches, the user must have the
 link:access-control.html#category_push[Push] access right with the
diff --git a/Documentation/prolog-change-facts.txt b/Documentation/prolog-change-facts.txt
index cd97223..cbd4070 100644
--- a/Documentation/prolog-change-facts.txt
+++ b/Documentation/prolog-change-facts.txt
@@ -4,7 +4,8 @@
 the Prolog engine with a set of facts (current data) about this change.
 The following table provides an overview of the provided facts.
 
-IMPORTANT: All the terms listed below are defined in the `gerrit` package. To use any
+[IMPORTANT]
+All the terms listed below are defined in the `gerrit` package. To use any
 of them we must use a qualified name like `gerrit:change_branch(X)`.
 
 .Prolog facts about the current change
@@ -56,6 +57,9 @@
                       |`current_user(user(anonymous)).`
                       |`current_user(user(peer_daemon)).`
                       |`current_user(user(replication)).`
+
+|`uploader/1`     |`uploader(user(1000000)).`
+    |Uploader as `user(ID)` term. ID is the numeric account ID
 |=============================================================================
 
 In addition Gerrit provides a set of built-in helper predicates that can be used
@@ -94,7 +98,8 @@
 
 |=============================================================================
 
-NOTE: for a complete list of built-in helpers read the `gerrit_common.pl` and
+[NOTE]
+For a complete list of built-in helpers read the `gerrit_common.pl` and
 all Java classes whose name matches `PRED_*.java` from Gerrit's source code.
 
 GERRIT
diff --git a/Documentation/prolog-cookbook.txt b/Documentation/prolog-cookbook.txt
index b53da4b..cced53e2 100644
--- a/Documentation/prolog-cookbook.txt
+++ b/Documentation/prolog-cookbook.txt
@@ -17,8 +17,9 @@
 submittable. For a change that is not submittable, the set of needed criteria
 is displayed in the Gerrit UI.
 
-NOTE: Loading and executing Prolog submit rules may be disabled by setting
-`rules.enabled=false` in the Gerrit config file (see
+[NOTE]
+Loading and executing Prolog submit rules may be disabled by setting
+`rules.enable=false` in the Gerrit config file (see
 link:config-gerrit.html#_a_id_rules_a_section_rules[rules section])
 
 link:https://groups.google.com/d/topic/repo-discuss/wJxTGhlHZMM/discussion[This
@@ -48,6 +49,13 @@
 Prolog based submit type computes a submit type for each change. The computed
 submit type is shown on the change screen for each change.
 
+When submitting changes in a batch using "Submit including ancestors" or "Submit
+whole topic", submit type rules may not be used to mix submit types on a single
+branch, and trying to submit such a batch will fail. This avoids potentially
+confusing behavior and spurious submit failures. It is recommended to only use
+submit type rules to change submit types for an entire branch, which avoids this
+situation.
+
 == Prolog Language
 This document is not a complete Prolog tutorial.
 link:http://en.wikipedia.org/wiki/Prolog[This Wikipedia page on Prolog] is a
@@ -66,7 +74,8 @@
 link:pgm-prolog-shell.html[prolog-shell] program which opens an interactive
 Prolog interpreter shell.
 
-NOTE: The interactive shell is just a prolog shell, it does not load
+[NOTE]
+The interactive shell is just a prolog shell, it does not load
 a gerrit server environment and thus is not intended for
 xref:TestingSubmitRules[testing submit rules].
 
@@ -85,14 +94,14 @@
 checkout the `refs/meta/config` branch in order to create or edit the `rules.pl`
 file:
 
-====
+----
   $ git fetch origin refs/meta/config:config
   $ git checkout config
   ... edit or create the rules.pl file
   $ git add rules.pl
   $ git commit -m "My submit rules"
   $ git push origin HEAD:refs/meta/config
-====
+----
 
 [[HowToWriteSubmitRules]]
 == How to write submit rules
@@ -106,14 +115,14 @@
 `C` on top of the `rules.pl` file and then consults it. The set of facts about
 the change `C` will look like:
 
-====
+----
   :- package gerrit.                                                   <1>
 
   commit_author(user(1000000), 'John Doe', 'john.doe@example.com').    <2>
   commit_committer(user(1000000), 'John Doe', 'john.doe@example.com'). <3>
   commit_message('Add plugin support to Gerrit').                      <4>
   ...
-====
+----
 
 <1> Gerrit will provide its facts in a package named `gerrit`. This means we
 have to use qualified names when writing our code and referencing these facts.
@@ -132,31 +141,33 @@
 an expectation on the format and value of the result of the `submit_rule`
 predicate which is expected to be a `submit` term of the following format:
 
-====
+----
   submit(label(label-name, status) [, label(label-name, status)]*)
-====
+----
 
 where `label-name` is usually `'Code-Review'` or `'Verified'` but could also
 be any other string (see examples below). The `status` is one of:
 
-* `ok(user(ID))` or just `ok(_)` if user info is not important. This status is
-  used to tell that this label/category has been met.
+* `ok(user(ID))`. This status is used to tell that this label/category has been
+  met.
 * `need(_)` is used to tell that this label/category is needed for the change to
-   become submittable.
-* `reject(user(ID))` or just `reject(_)`. This status is used to tell that this
-   label/category is blocking submission of the change.
+  become submittable.
+* `reject(user(ID))`. This status is used to tell that this label/category is
+  blocking submission of the change.
 * `impossible(_)` is used when the logic knows that the change cannot be submitted
-   as-is. This is meant for cases where the logic requires members of a specific
-   group to apply a specific label on a change, but no users are in that group.
-   This is usually caused by misconfiguration of permissions.
+  as-is. This is meant for cases where the logic requires members of a specific
+  group to apply a specific label on a change, but no users are in that group.
+  This is usually caused by misconfiguration of permissions.
 * `may(_)` allows expression of approval categories that are optional, i.e.
   could either be set or unset without ever influencing whether the change
   could be submitted.
 
-NOTE: For a change to be submittable all `label` terms contained in the returned
+[NOTE]
+For a change to be submittable all `label` terms contained in the returned
 `submit` term must have either `ok` or `may` status.
 
-IMPORTANT: Gerrit will let the Prolog engine continue searching for solutions of
+[IMPORTANT]
+Gerrit will let the Prolog engine continue searching for solutions of
 the `submit_rule(X)` query until it finds the first one where all labels in the
 return result have either status `ok` or `may` or there are no more solutions.
 If a solution where all labels have status `ok` is found then all previously
@@ -166,11 +177,12 @@
 
 Here some examples of possible return values from the `submit_rule` predicate:
 
-====
-  submit(label('Code-Review', ok(_)))                               <1>
-  submit(label('Code-Review', ok(_)), label('Verified', reject(_))) <2>
+----
+  submit(label('Code-Review', ok(user(ID))))                        <1>
+  submit(label('Code-Review', ok(user(ID))),
+      label('Verified', reject(user(ID))))                          <2>
   submit(label('Author-is-John-Doe', need(_))                       <3>
-====
+----
 
 <1> label `'Code-Review'` is met. As there are no other labels in the
     return result, the change is submittable.
@@ -178,7 +190,7 @@
 <3> label `'Author-is-John-Doe'` is needed for the change to become submittable.
     Note that this tells nothing about how this criteria will be met. It is up
     to the implementer of the `submit_rule` to return
-    `label('Author-is-John-Doe', ok(_))` when this criteria is met.  Most
+    `label('Author-is-John-Doe', ok(user(ID)))` when this criteria is met. Most
     likely, it will have to match against `gerrit:commit_author` in order to
     check if this criteria is met. This will become clear through the examples
     below.
@@ -210,10 +222,9 @@
 of the `submit_rule`. Therefore, the `submit_filter` predicate has two
 parameters:
 
-====
+----
   submit_filter(In, Out) :- ...
-====
-
+----
 Gerrit will invoke `submit_filter` with the `In` parameter containing a `submit`
 structure produced by the `submit_rule` and will take the value of the `Out`
 parameter as the result.
@@ -223,7 +234,8 @@
 of the top-most `submit_filter` is the final result of the submit rule that
 is used to decide whether a change is submittable or not.
 
-IMPORTANT: `submit_filter` is a mechanism for Gerrit administrators to implement
+[IMPORTANT]
+`submit_filter` is a mechanism for Gerrit administrators to implement
 and enforce submit rules that would apply to all projects while `submit_rule` is
 a mechanism for project owners to implement project specific submit rules.
 However, project owners who own several projects could also make use of
@@ -233,7 +245,7 @@
 
 The following "drawing" illustrates the order of the invocation and the chaining
 of the results of the `submit_rule` and `submit_filter` predicates.
-====
+----
   All-Projects
   ^   submit_filter(B, S) :- ...  <4>
   |
@@ -248,7 +260,7 @@
   |
   MyProject
       submit_rule(X) :- ...       <1>
-====
+----
 
 <1> The `submit_rule` of `MyProject` is invoked first.
 <2> The result `X` is filtered through the `submit_filter` from the `Parent-1`
@@ -260,7 +272,8 @@
 `submit_filter` in the `All-Projects` project. The value in `S` is the final
 value of the submit rule evaluation.
 
-NOTE: If `MyProject` doesn't define its own `submit_rule` Gerrit will invoke the
+[NOTE]
+If `MyProject` doesn't define its own `submit_rule` Gerrit will invoke the
 default implementation of submit rule that is named `gerrit:default_submit` and
 its result will be filtered as described above.
 
@@ -282,9 +295,9 @@
 Submit type filter works the same way as the xref:SubmitFilter[Submit Filter]
 where the name of the filter predicate is `submit_type_filter`.
 
-====
+----
   submit_type_filter(In, Out).
-====
+----
 
 Gerrit will invoke `submit_type_filter` with the `In` parameter containing a
 result of the `submit_type` and will take the value of the `Out` parameter as
@@ -299,9 +312,9 @@
 and executes the `submit_rule`. It optionally reads the rule from from `stdin`
 to facilitate easy testing.
 
-====
+----
   $ cat rules.pl | ssh gerrit_srv gerrit test-submit rule I45e080b105a50a625cc8e1fb5b357c0bfabe6d68 -s
-====
+----
 
 == Prolog vs Gerrit plugin for project specific submit rules
 Since version 2.5 Gerrit supports plugins and extension points. A plugin or an
@@ -339,7 +352,7 @@
 [source,prolog]
 ----
 submit_rule(submit(W)) :-
-    W = label('Any-Label-Name', ok(_)).
+    W = label('Any-Label-Name', ok(user(1000000))).
 ----
 
 In this case we make no use of facts about the change. We don't need it as we
@@ -348,6 +361,14 @@
 `'Verified'` categories as labels with these names are not part of the return
 result. The `'Any-Label-Name'` could really be any string.
 
+The `user(1000000)` represents the user whose account ID is `1000000`.
+
+[NOTE]
+Instead of the account ID `1000000` we could have used any other account ID.
+The following examples will use `user(ID)` instead of `user(1000000)` because
+it is easier to read and doesn't suggest that there is anything special with
+the account ID `1000000`.
+
 === Example 2: Every change submittable and voting in the standard categories possible
 This is continuation of the previous example where, in addition, to making
 every change submittable we want to enable voting in the standard
@@ -357,8 +378,8 @@
 [source,prolog]
 ----
 submit_rule(submit(CR, V)) :-
-    CR = label('Code-Review', ok(_)),
-    V = label('Verified', ok(_)).
+    CR = label('Code-Review', ok(user(ID))),
+    V = label('Verified', ok(user(ID))).
 ----
 
 Since for every change all label statuses are `'ok'` every change will be
@@ -373,7 +394,7 @@
 [source,prolog]
 ----
 submit_rule(submit(R)) :-
-    R = label('Any-Label-Name', reject(_)).
+    R = label('Any-Label-Name', reject(user(ID))).
 ----
 
 Since for any change we return only one label with status `reject`, no change
@@ -427,7 +448,7 @@
     N = label('Some-Condition', need(_)).
 
 submit_rule(submit(OK)) :-
-    OK = label('Another-Condition', ok(_)).
+    OK = label('Another-Condition', ok(user(ID))).
 ----
 
 The `'Need Some-Condition'` will not be shown in the UI because of the result of
@@ -439,7 +460,7 @@
 [source,prolog]
 ----
 submit_rule(submit(OK)) :-
-    OK = label('Another-Condition', ok(_)).
+    OK = label('Another-Condition', ok(user(ID))).
 
 submit_rule(submit(N)) :-
     N = label('Some-Condition', need(_)).
@@ -475,8 +496,8 @@
     Author = label('Author-is-John-Doe', need(_)).
 
 submit_rule(submit(Author)) :-
-    gerrit:commit_author(_, 'John Doe', _),
-    Author = label('Author-is-John-Doe', ok(_)).
+    gerrit:commit_author(A, 'John Doe', _),
+    Author = label('Author-is-John-Doe', ok(A)).
 ----
 
 In the second rule we return `ok` status for the `'Author-is-John-Doe'` label
@@ -496,8 +517,8 @@
     Author = label('Author-is-John-Doe', need(_)).
 
 submit_rule(submit(Author)) :-
-    gerrit:commit_author(_, _, 'john.doe@example.com'),
-    Author = label('Author-is-John-Doe', ok(_)).
+    gerrit:commit_author(A, _, 'john.doe@example.com'),
+    Author = label('Author-is-John-Doe', ok(A)).
 ----
 
 or by user id (assuming it is `1000000`):
@@ -509,8 +530,9 @@
     Author = label('Author-is-John-Doe', need(_)).
 
 submit_rule(submit(Author)) :-
-    gerrit:commit_author(user(1000000), _, _),
-    Author = label('Author-is-John-Doe', ok(_)).
+    U = user(1000000),
+    gerrit:commit_author(U, _, _),
+    Author = label('Author-is-John-Doe', ok(U)).
 ----
 
 or by a combination of these 3 attributes:
@@ -522,8 +544,8 @@
     Author = label('Author-is-John-Doe', need(_)).
 
 submit_rule(submit(Author)) :-
-    gerrit:commit_author(_, 'John Doe', 'john.doe@example.com'),
-    Author = label('Author-is-John-Doe', ok(_)).
+    gerrit:commit_author(A, 'John Doe', 'john.doe@example.com'),
+    Author = label('Author-is-John-Doe', ok(A)).
 ----
 
 === Example 7: Make change submittable if commit message starts with "Fix "
@@ -549,13 +571,15 @@
 
 submit_rule(submit(Fix)) :-
     gerrit:commit_message(M), name(M, L), starts_with(L, "Fix "),
-    Fix = label('Commit-Message-starts-with-Fix', ok(_)).
+    gerrit:commit_author(A),
+    Fix = label('Commit-Message-starts-with-Fix', ok(A)).
 
 starts_with(L, []).
 starts_with([H|T1], [H|T2]) :- starts_with(T1, T2).
 ----
 
-NOTE: The `name/2` embedded predicate is used to convert a string symbol into a
+[NOTE]
+The `name/2` embedded predicate is used to convert a string symbol into a
 list of characters. A string `abc` is converted into a list of characters `[97,
 98, 99]`.  A double quoted string in Prolog is just a shortcut for creating a
 list of characters. `"abc"` is a shortcut for `[97, 98, 99]`. This is why we use
@@ -573,7 +597,8 @@
 
 submit_rule(submit(Fix)) :-
     gerrit:commit_message_matches('^Fix '),
-    Fix = label('Commit-Message-starts-with-Fix', ok(_)).
+    gerrit:commit_author(A),
+    Fix = label('Commit-Message-starts-with-Fix', ok(A)).
 ----
 
 The previous example could also be written so that it first checks if the commit
@@ -585,7 +610,8 @@
 ----
 submit_rule(submit(Fix)) :-
     gerrit:commit_message_matches('^Fix '),
-    Fix = label('Commit-Message-starts-with-Fix', ok(_)),
+    gerrit:commit_author(A),
+    Fix = label('Commit-Message-starts-with-Fix', ok(A)),
     !.
 
 % Message does not start with 'Fix ' so Fix is needed to submit
@@ -682,8 +708,8 @@
 
 This example uses the `univ` operator `=..` to "unpack" the result of the
 default_submit, which is a structure of the form `submit(label('Code-Review',
-ok(_)), label('Verified', need(_)), ...)` into a list like `[submit,
-label('Code-Review', ok(_)), label('Verified', need(_)), ...]`.  Then we
+ok(user(ID))), label('Verified', need(_)), ...)` into a list like `[submit,
+label('Code-Review', ok(user(ID))), label('Verified', need(_)), ...]`.  Then we
 process the tail of the list (the list of labels) as a Prolog list, which is
 much easier than processing a structure. In the end we use the same `univ`
 operator to convert the resulting list of labels back into a `submit` structure
@@ -734,7 +760,7 @@
 Which of these two behaviors is desired will always depend on how a particular
 Gerrit server is managed.
 
-==== Example 9: Remove the `Verified` category
+=== Example 9: Remove the `Verified` category
 A project has no build and test. It consists of only text files and needs only
 code review.  We want to remove the `Verified` category from this project so
 that `Code-Review+2` is the only criteria for a change to become submittable.
@@ -802,7 +828,7 @@
     N = label('Non-Author-Code-Review', need(_)).
 
 base(CR) :-
-    gerrit:max_with_block(-2, 2, 'Code-Review', CR),
+    gerrit:max_with_block(-2, 2, 'Code-Review', CR).
 ----
 
 === Example 11: Remove the `Verified` category from all projects
@@ -999,37 +1025,13 @@
 submit_type(fast_forward_only) :-
     gerrit:change_branch(B), regex_matches('refs/heads/stable.*', B),
     !.
-submit_type(T) :- gerrit:project_default_submit_type(T)
+submit_type(T) :- gerrit:project_default_submit_type(T).
 ----
 
 The first `submit_type` predicate defines the `Fast Forward Only` submit type
 for `+refs/heads/stable.*+` branches. The second `submit_type` predicate returns
 the project's default submit type.
 
-=== Example 3: Don't require `Fast Forward Only` if only documentation was changed
-Like in the previous example we want the `Fast Forward Only` submit type for the
-`+refs/heads/stable*+` branches.  However, if only documentation was changed
-(only `+*.txt+` files), then we allow project's default submit type for such
-changes.
-
-`rules.pl`
-[source,prolog]
-----
-submit_type(fast_forward_only) :-
-    gerrit:commit_delta('(?<!\.txt)$'),
-    gerrit:change_branch(B), regex_matches('refs/heads/stable.*', B),
-    !.
-submit_type(T) :- gerrit:project_default_submit_type(T)
-----
-
-The `gerrit:commit_delta('(?<!\.txt)$')` succeeds if the change contains a file
-whose name doesn't end with `.txt` The rest of this rule is same like in the
-previous example.
-
-If all file names in the change end with `.txt`, then the
-`gerrit:commit_delta('(?<!\.txt)$')` will fail as no file name will match this
-regular expression.
-
 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/replace_macros.py b/Documentation/replace_macros.py
index fec4a58..baf08e7 100755
--- a/Documentation/replace_macros.py
+++ b/Documentation/replace_macros.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python
+# coding=utf-8
 # Copyright (C) 2013 The Android Open Source Project
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -60,9 +61,32 @@
 SEARCH_BOX = """
 
 ++++
-<div style="position:absolute; right:20px; top:20px;">
-<input type="text" id="docSearch" size="70" />
-<button type="button" id="searchBox">Search</button>
+<div style="
+  position:fixed;
+  top:0px;
+  right:0px;
+  text-align:
+  right;
+  padding-top:2px;
+  padding-right:0.5em;
+  padding-bottom:2px;">
+<input size="40"
+  style="line-height: 0.75em;font-size: 0.75em;"
+  id="docSearch"
+  type="text">
+<button style="
+  background:none!important;
+  border:none;
+  padding:0!important;
+  vertical-align:bottom;
+  font-family:'Open Sans','DejaVu Sans',sans-serif;
+  font-size:0.8em;
+  color:#1d4b8f;
+  text-decoration:none;"
+  type="button"
+  id="searchBox">
+  Search
+</button>
 <script type="text/javascript">
 var f = function() {
   window.location = '../#/Documentation/' +
@@ -148,11 +172,14 @@
           a.setAttribute('href', '#' + id);
           a.setAttribute('style', 'position: absolute;'
               + ' left: ' + (element.offsetLeft - 16 - 2 * 4) + 'px;'
-              + ' padding-left: 4px; padding-right: 4px; padding-top:4px;');
-          var img = document.createElement('img');
-          img.setAttribute('src', 'images/link.png');
-          img.setAttribute('style', 'background-color: #FFFFFF;');
-          a.appendChild(img);
+              + ' padding-left: 4px; padding-right: 4px;');
+          var span = document.createElement('span');
+          span.setAttribute('style', 'height: ' + element.offsetHeight + 'px;'
+              + ' display: inline-block; vertical-align: baseline;'
+              + ' font-size: 16px; text-decoration: none; color: grey;');
+          a.appendChild(span);
+          var link = document.createTextNode('🔗');
+          span.appendChild(link);
           element.insertBefore(a, element.firstChild);
 
           // remove the link icon when the mouse is moved away,
@@ -160,14 +187,16 @@
           hide = function(evt) {
             if (document.elementFromPoint(evt.clientX, evt.clientY) != element
                 && document.elementFromPoint(evt.clientX, evt.clientY) != a
-                && document.elementFromPoint(evt.clientX, evt.clientY) != img
+                && document.elementFromPoint(evt.clientX, evt.clientY) != span
+                && document.elementFromPoint(evt.clientX, evt.clientY) != link
                 && element.contains(a)) {
               element.removeChild(a);
             }
           }
           element.onmouseout = hide;
           a.onmouseout = hide;
-          img.onmouseout = hide;
+          span.onmouseout = hide;
+          link.onmouseout = hide;
         }
       }
     }
diff --git a/Documentation/rest-api-access.txt b/Documentation/rest-api-access.txt
index ee3e8ce..61ea582 100644
--- a/Documentation/rest-api-access.txt
+++ b/Documentation/rest-api-access.txt
@@ -334,10 +334,10 @@
 |`force`        |not set if `false`|
 Whether the force flag is set.
 |`min`          |
-not set if range if empty (from `0` to `0`) or not set|
+not set if range is empty (from `0` to `0`) or not set|
 The min value of the permission range.
 |`max`          |
-not set if range if empty (from `0` to `0`) or not set|
+not set if range is empty (from `0` to `0`) or not set|
 The max value of the permission range.
 |==================================
 
diff --git a/Documentation/rest-api-accounts.txt b/Documentation/rest-api-accounts.txt
index 5459306..e784c1c 100644
--- a/Documentation/rest-api-accounts.txt
+++ b/Documentation/rest-api-accounts.txt
@@ -7,19 +7,76 @@
 [[account-endpoints]]
 == Account Endpoints
 
-[[suggest-account]]
-=== Suggest Account
+[[query-account]]
+=== Query Account
 --
 'GET /accounts/'
 --
 
-Suggest users for a given query `q` and result limit `n`. If result
-limit is not passed, then the default 10 is used. Returns a list of
-matching link:#account-info[AccountInfo] entities.
+Queries accounts visible to the caller. The
+link:user-search-accounts.html#_search_operators[query string] must be
+provided by the `q` parameter. The `n` parameter can be used to limit
+the returned results.
+
+As result a list of link:#account-info[AccountInfo] entities is
+returned.
 
 .Request
 ----
-  GET /accounts/?q=John HTTP/1.0
+  GET /accounts/?q=name:John+email:example.com&n=2 HTTP/1.0
+----
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  [
+    {
+      "_account_id": 1000096,
+    },
+    {
+      "_account_id": 1001439,
+      "_more_accounts": true
+    }
+  ]
+----
+
+If the number of accounts matching the query exceeds either the
+internal limit or a supplied `n` query parameter, the last account
+object has a `_more_accounts: true` JSON field set.
+
+The `S` or `start` query parameter can be supplied to skip a number
+of accounts from the list.
+
+Additional fields can be obtained by adding `o` parameters, each
+option slows down the query response time to the client so they are
+generally disabled by default. Optional fields are:
+
+[[details]]
+--
+* `DETAILS`: Includes full name, preferred email, username and avatars
+for each account.
+--
+
+[[all-emails]]
+--
+* `ALL_EMAILS`: Includes all registered emails.
+--
+
+[[suggest-account]]
+To get account suggestions set the parameter `suggest` and provide the
+typed substring as query `q`. If a result limit `n` is not specified,
+then the default 10 is used.
+
+For account suggestions link:#details[account details] and
+link:#all-emails[all emails] are always returned.
+
+.Request
+----
+  GET /accounts/?suggest&q=John HTTP/1.0
 ----
 
 .Response
@@ -420,6 +477,43 @@
   HTTP/1.1 204 No Content
 ----
 
+[[get-oauth-token]]
+=== Get OAuth Access Token
+--
+'GET /accounts/link:#account-id[\{account-id\}]/oauthtoken'
+--
+
+Returns a previously obtained OAuth access token.
+
+.Request
+----
+  GET /accounts/self/oauthtoken HTTP/1.1
+----
+
+As a response, an link:#oauth-token-info[OAuthTokenInfo] entity is returned
+that describes the OAuth access token.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+   )]}'
+    {
+      "username": "johndow",
+      "resource_host": "gerrit.example.org",
+      "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOi",
+      "provider_id": "oauth-plugin:oauth-provider",
+      "expires_at": "922337203775807",
+      "type": "bearer"
+    }
+----
+
+If there is no token available, or the token has already expired,
+"`404 Not Found`" is returned as response. Requests to obtain an access
+token of another user are rejected with "`403 Forbidden`".
+
 [[list-account-emails]]
 === List Account Emails
 --
@@ -500,12 +594,16 @@
 configured, the added email address must belong to a domain that is
 allowed, unless `no_confirmation` is set.
 
-In the request body additional data for the email address can be
-provided as link:#email-input[EmailInput].
+The link:#email-input[EmailInput] object in the request body may
+contain additional options for the email address.
 
 .Request
 ----
   PUT /accounts/self/emails/john.doe@example.com HTTP/1.0
+  Content-Type: application/json; charset=UTF-8
+  Content-Length: 3
+
+  {}
 ----
 
 As response the new email address is returned as
@@ -641,6 +739,9 @@
 
 The SSH public key must be provided as raw content in the request body.
 
+Trying to add an SSH key that already exists succeeds, but no new SSH
+key is persisted.
+
 .Request
 ----
   POST /accounts/self/sshkeys HTTP/1.0
@@ -1086,6 +1187,14 @@
 As result the account preferences of the user are returned as a
 link:#preferences-info[PreferencesInfo] entity.
 
+Users may only retrieve the preferences for their own account,
+unless they are an
+link:access-control.html#administrators[Administrator] or a member
+of a group that is granted the
+link:access-control.html#capability_modifyAccount[ModifyAccount]
+capability, in which case they can retrieve the preferences for
+any account.
+
 .Response
 ----
   HTTP/1.1 200 OK
@@ -1097,11 +1206,13 @@
     "changes_per_page": 25,
     "show_site_header": true,
     "use_flash_clipboard": true,
+    "download_command": "CHECKOUT",
     "date_format": "STD",
     "time_format": "HHMM_12",
+    "diff_view": "SIDE_BY_SIDE",
     "size_bar_in_change_table": true,
     "review_category_strategy": "ABBREV",
-    "diff_view": "SIDE_BY_SIDE",
+    "mute_common_path_prefixes": true,
     "my": [
       {
         "url": "#/dashboard/self",
@@ -1151,11 +1262,13 @@
     "changes_per_page": 50,
     "show_site_header": true,
     "use_flash_clipboard": true,
+    "download_command": "CHECKOUT",
     "date_format": "STD",
     "time_format": "HHMM_12",
     "size_bar_in_change_table": true,
     "review_category_strategy": "NAME",
     "diff_view": "SIDE_BY_SIDE",
+    "mute_common_path_prefixes": true,
     "my": [
       {
         "url": "#/dashboard/self",
@@ -1199,11 +1312,13 @@
     "changes_per_page": 50,
     "show_site_header": true,
     "use_flash_clipboard": true,
+    "download_command": "CHECKOUT",
     "date_format": "STD",
     "time_format": "HHMM_12",
     "size_bar_in_change_table": true,
     "review_category_strategy": "NAME",
     "diff_view": "SIDE_BY_SIDE",
+    "mute_common_path_prefixes": true,
     "my": [
       {
         "url": "#/dashboard/self",
@@ -1353,6 +1468,7 @@
     "key_map_type": "VIM",
     "tab_size": 4,
     "line_length": 80,
+    "indent_unit": 2,
     "cursor_blink_rate": 530,
     "hide_top_menu": true,
     "show_whitespace_errors": true,
@@ -1384,6 +1500,7 @@
     "key_map_type": "VIM",
     "tab_size": 4,
     "line_length": 80,
+    "indent_unit": 2,
     "cursor_blink_rate": 530,
     "hide_top_menu": true,
     "show_tabs": true,
@@ -1396,23 +1513,166 @@
   }
 ----
 
-The response is "`204 No Content`"
+As result the new edit preferences of the user are returned as a
+link:#edit-preferences-info[EditPreferencesInfo] entity.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json;charset=UTF-8
+
+  )]}'
+  {
+    "theme": "ECLIPSE",
+    "key_map_type": "VIM",
+    "tab_size": 4,
+    "line_length": 80,
+    "cursor_blink_rate": 530,
+    "hide_top_menu": true,
+    "show_whitespace_errors": true,
+    "hide_line_numbers": true,
+    "match_brackets": true,
+    "auto_close_brackets": true
+  }
+----
+
+[[get-watched-projects]]
+=== Get Watched Projects
+--
+'GET /accounts/link:#account-id[\{account-id\}]/watched.projects'
+--
+
+Retrieves all projects a user is watching.
+
+.Request
+----
+  GET /a/accounts/self/watched.projects HTTP/1.0
+----
+
+As result the watched projects of the user are returned as a list of
+link:#project-watch-info[ProjectWatchInfo] entities.
+The result is sorted by project name in ascending order.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  [
+    {
+      "project": "Test Project 1",
+      "notify_new_changes": true,
+      "notify_new_patch_sets": true,
+      "notify_all_comments": true,
+    },
+    {
+      "project": "Test Project 2",
+      "filter": "branch:experimental",
+      "notify_all_comments": true,
+      "notify_submitted_changes": true,
+      "notify_abandoned_changes": true
+    }
+  ]
+----
+
+[[set-watched-projects]]
+=== Add/Update a List of Watched Project Entities
+--
+'POST /accounts/link:#account-id[\{account-id\}]/watched.projects'
+--
+
+Add new projects to watch or update existing watched projects.
+Projects that are already watched by a user will be updated with
+the provided configuration. All other projects in the request
+will be watched using the provided configuration. The posted body
+can contain link:#project-watch-info[ProjectWatchInfo] entities.
+Omitted boolean values will be set to false.
+
+.Request
+----
+  POST /a/accounts/self/watched.projects HTTP/1.0
+  Content-Type: application/json;charset=UTF-8
+
+  [
+    {
+      "project": "Test Project 1",
+      "notify_new_changes": true,
+      "notify_new_patch_sets": true,
+      "notify_all_comments": true,
+    }
+  ]
+----
+
+As result the watched projects of the user are returned as a list of
+link:#project-watch-info[ProjectWatchInfo] entities.
+The result is sorted by project name in ascending order.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  [
+    {
+      "project": "Test Project 1",
+      "notify_new_changes": true,
+      "notify_new_patch_sets": true,
+      "notify_all_comments": true,
+    },
+    {
+      "project": "Test Project 2",
+      "notify_new_changes": true,
+      "notify_new_patch_sets": true,
+      "notify_all_comments": true,
+    }
+  ]
+----
+
+[[delete-watched-projects]]
+=== Delete Watched Projects
+--
+'POST /accounts/link:#account-id[\{account-id\}]/watched.projects:delete'
+--
+
+Projects posted to this endpoint will no longer be watched. The posted body
+can contain a list of link:#project-watch-info[ProjectWatchInfo] entities.
+
+.Request
+----
+  POST /a/accounts/self/watched.projects:delete HTTP/1.0
+  Content-Type: application/json;charset=UTF-8
+
+  [
+    {
+      "project": "Test Project 1",
+      "filter": "branch:master"
+    }
+  ]
+----
 
 .Response
 ----
   HTTP/1.1 204 No Content
 ----
 
-[[get-starred-changes]]
-=== Get Starred Changes
+[[default-star-endpoints]]
+== Default Star Endpoints
+
+[[get-changes-with-default-star]]
+=== Get Changes With Default Star
 --
 'GET /accounts/link:#account-id[\{account-id\}]/starred.changes'
 --
 
-Gets the changes starred by the identified user account. This
-URL endpoint is functionally identical to the changes query
-`GET /changes/?q=is:starred`. The result is a list of
-link:rest-api-changes.html#change-info[ChangeInfo] entities.
+Gets the changes that were starred with the default star by the
+identified user account. This URL endpoint is functionally identical
+to the changes query `GET /changes/?q=is:starred`. The result is a list
+of link:rest-api-changes.html#change-info[ChangeInfo] entities.
 
 .Request
 ----
@@ -1436,7 +1696,14 @@
       "status": "NEW",
       "created": "2013-02-01 09:59:32.126000000",
       "updated": "2013-02-21 11:16:36.775000000",
+      "starred": true,
+      "stars": [
+        "star"
+      ],
       "mergeable": true,
+      "submittable": false,
+      "insertions": 145,
+      "deletions": 12,
       "_number": 3965,
       "owner": {
         "name": "John Doe"
@@ -1446,14 +1713,15 @@
 ----
 
 [[star-change]]
-=== Star Change
+=== Put Default Star On Change
 --
 'PUT /accounts/link:#account-id[\{account-id\}]/starred.changes/link:rest-api-changes.html#change-id[\{change-id\}]'
 --
 
-Star a change. Starred changes are returned for the search query
-`is:starred` or `starredby:USER` and automatically notify the user
-whenever updates are made to the change.
+Star a change with the default label. Changes starred with the default
+label are returned for the search query `is:starred` or `starredby:USER`
+and automatically notify the user whenever updates are made to the
+change.
 
 .Request
 ----
@@ -1466,12 +1734,12 @@
 ----
 
 [[unstar-change]]
-=== Unstar Change
+=== Remove Default Star From Change
 --
 'DELETE /accounts/link:#account-id[\{account-id\}]/starred.changes/link:rest-api-changes.html#change-id[\{change-id\}]'
 --
 
-Unstar a change. Removes the starred flag, stopping notifications.
+Remove the default star label from a change. This stops notifications.
 
 .Request
 ----
@@ -1483,6 +1751,214 @@
   HTTP/1.1 204 No Content
 ----
 
+[[star-endpoints]]
+== Star Endpoints
+
+[[get-starred-changes]]
+=== Get Starred Changes
+--
+'GET /accounts/link:#account-id[\{account-id\}]/stars.changes'
+--
+
+Gets the changes that were starred with any label by the identified
+user account. This URL endpoint is functionally identical to the
+changes query `GET /changes/?q=has:stars`. The result is a list of
+link:rest-api-changes.html#change-info[ChangeInfo] entities.
+
+.Request
+----
+  GET /a/accounts/self/stars.changes
+----
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  [
+    {
+      "id": "myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940",
+      "project": "myProject",
+      "branch": "master",
+      "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
+      "subject": "Implementing Feature X",
+      "status": "NEW",
+      "created": "2013-02-01 09:59:32.126000000",
+      "updated": "2013-02-21 11:16:36.775000000",
+      "stars": [
+        "ignore",
+        "risky"
+      ],
+      "mergeable": true,
+      "submittable": false,
+      "insertions": 145,
+      "deletions": 12,
+      "_number": 3965,
+      "owner": {
+        "name": "John Doe"
+      }
+    }
+  ]
+----
+
+[[get-stars]]
+=== Get Star Labels From Change
+--
+'GET /accounts/link:#account-id[\{account-id\}]/stars.changes/link:rest-api-changes.html#change-id[\{change-id\}]'
+--
+
+Get star labels from a change.
+
+.Request
+----
+  GET /a/accounts/self/stars.changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0
+----
+
+As response the star labels that the user applied on the change are
+returned. The labels are lexicographically sorted.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  [
+    "blue",
+    "green",
+    "red"
+  ]
+----
+
+[[set-stars]]
+=== Update Star Labels On Change
+--
+'POST /accounts/link:#account-id[\{account-id\}]/stars.changes/link:rest-api-changes.html#change-id[\{change-id\}]'
+--
+
+Update star labels on a change. The star labels to be added/removed
+must be specified in the request body as link:#stars-input[StarsInput]
+entity. Starred changes are returned for the search query `has:stars`.
+
+.Request
+----
+  POST /a/accounts/self/stars.changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940 HTTP/1.0
+  Content-Type: application/json; charset=UTF-8
+
+  {
+    "add": [
+      "blue",
+      "red"
+    ],
+    "remove": [
+      "yellow"
+    ]
+  }
+----
+
+As response the star labels that the user applied on the change are
+returned. The labels are lexicographically sorted.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  [
+    "blue",
+    "green",
+    "red"
+  ]
+----
+
+[[list-contributor-agreements]]
+=== List Contributor Agreements
+--
+'GET /accounts/link:#account-id[\{account-id\}]/agreements'
+--
+
+Gets a list of the user's signed contributor agreements.
+
+.Request
+----
+  GET /a/accounts/self/agreements HTTP/1.0
+----
+
+As response the user's signed agreements are returned as a list
+of link:#contributor-agreement-info[ContributorAgreementInfo] entities.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  [
+    {
+      "name": "Individual",
+      "description": "If you are going to be contributing code on your own, this is the one you want. You can sign this one online.",
+      "url": "static/cla_individual.html"
+    }
+  ]
+----
+
+[[sign-contributor-agreement]]
+=== Sign Contributor Agreement
+--
+'PUT /accounts/link:#account-id[\{account-id\}]/agreements'
+--
+
+Signs a contributor agreement.
+
+The contributor agreement must be provided in the request body as
+a link:#contributor-agreement-input[ContributorAgreementInput].
+
+.Request
+----
+  PUT /accounts/self/agreements HTTP/1.0
+  Content-Type: application/json; charset=UTF-8
+
+  {
+    "name": "Individual"
+  }
+----
+
+As response the contributor agreement name is returned.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  "Individual"
+----
+
+[[index-account]]
+=== Index Account
+--
+'POST /accounts/link:#account-id[\{account-id\}]/index'
+--
+
+Adds or updates the account in the secondary index.
+
+.Request
+----
+  POST /accounts/1000096/index HTTP/1.0
+----
+
+.Response
+----
+  HTTP/1.1 204 No Content
+----
+
 [[ids]]
 == IDs
 
@@ -1529,7 +2005,7 @@
 
 [[account-detail-info]]
 === AccountDetailInfo
-The `AccountDetailInfo` entity contains detailled information about an
+The `AccountDetailInfo` entity contains detailed information about an
 account.
 
 `AccountDetailInfo` has the same fields as link:#account-info[
@@ -1548,20 +2024,34 @@
 The `AccountInfo` entity contains information about an account.
 
 [options="header",cols="1,^1,5"]
-|===========================
-|Field Name    ||Description
-|`_account_id` ||The numeric ID of the account.
-|`name`        |optional|The full name of the user. +
-Only set if link:rest-api-changes.html#detailed-accounts[detailed
-account information] is requested.
-|`email`       |optional|
+|===============================
+|Field Name        ||Description
+|`_account_id`     ||The numeric ID of the account.
+|`name`            |optional|The full name of the user. +
+Only set if detailed account information is requested. +
+See option link:rest-api-changes.html#detailed-accounts[
+DETAILED_ACCOUNTS] for change queries +
+and option link:#details[DETAILS] for account queries.
+|`email`           |optional|
 The email address the user prefers to be contacted through. +
-Only set if link:rest-api-changes.html#detailed-accounts[detailed
-account information] is requested.
-|`username`    |optional|The username of the user. +
-Only set if link:rest-api-changes.html#detailed-accounts[detailed
-account information] is requested.
-|===========================
+Only set if detailed account information is requested. +
+See option link:rest-api-changes.html#detailed-accounts[
+DETAILED_ACCOUNTS] for change queries +
+and options link:#details[DETAILS] and link:#all-emails[
+ALL_EMAILS] for account queries.
+|`secondary_emails`|optional|
+A list of the secondary email addresses of the user. +
+Only set for account queries when the link:#all-emails[ALL_EMAILS]
+option is set.
+|`username`        |optional|The username of the user. +
+Only set if detailed account information is requested. +
+See option link:rest-api-changes.html#detailed-accounts[
+DETAILED_ACCOUNTS] for change queries +
+and option link:#details[DETAILS] for account queries.
+|`_more_accounts`  |optional, not set if `false`|
+Whether the query would deliver more results if not limited. +
+Only set on the last account that is returned.
+|===============================
 
 [[account-input]]
 === AccountInput
@@ -1655,6 +2145,31 @@
 link:access-control.html#capability_viewQueue[View Queue] capability.
 |=================================
 
+[[contributor-agreement-info]]
+=== ContributorAgreementInfo
+
+The `ContributorAgreementInfo` entity contains information about a
+contributor agreement.
+
+[options="header",cols="1,6"]
+|=================================
+|Field Name                 |Description
+|`name`                     |The name of the agreement.
+|`description`              |The description of the agreement.
+|`url`                      |The URL of the agreement.
+|=================================
+
+[[contributor-agreement-input]]
+=== ContributorAgreementInput
+The `ContributorAgreementInput` entity contains information about a
+new contributor agreement.
+
+[options="header",cols="1,6"]
+|=================================
+|Field Name                 |Description
+|`name`                     |The name of the agreement.
+|=================================
+
 [[diff-preferences-info]]
 === DiffPreferencesInfo
 The `DiffPreferencesInfo` entity contains information about the diff
@@ -1666,8 +2181,8 @@
 |`context`                     ||
 The number of lines of context when viewing a patch.
 |`theme`                       ||
-The CodeMirror theme. Currently only a subset of light and dark
-CodeMirror themes are supported.
+The CodeMirror theme name in upper case, for example `DEFAULT`. All the themes
+from the CodeMirror release that Gerrit is using are available.
 |`expand_all_comments`         |not set if `false`|
 Whether all inline comments should be automatically expanded.
 |`ignore_whitespace`           ||
@@ -1784,16 +2299,17 @@
 |===========================================
 |Field Name                    ||Description
 |`theme`                       ||
-The CodeMirror theme. Currently only a subset of light and dark
-CodeMirror themes are supported. Light themes `DEFAULT`, `ECLIPSE`,
-`ELEGANT`, `NEAT`. Dark themes `MIDNIGHT`, `NIGHT`, `TWILIGHT`.
+The CodeMirror theme name in upper case, for example `DEFAULT`. All the themes
+from the CodeMirror release that Gerrit is using are available.
 |`key_map_type`                ||
 The CodeMirror key map. Currently only a subset of key maps are
-supported: `DEFAULT`, `EMACS`, `VIM`.
+supported: `DEFAULT`, `EMACS`, `SUBLIME`, `VIM`.
 |`tab_size`                    ||
 Number of spaces that should be used to display one tab.
 |`line_length`                 ||
 Number of characters that should be displayed per line.
+|`indent_unit`                 ||
+Number of spaces that should be used for auto-indent.
 |`cursor_blink_rate`           ||
 Half-period in milliseconds used for cursor blinking.
 Setting it to 0 disables cursor blinking.
@@ -1906,6 +2422,22 @@
 password is deleted.
 |============================
 
+[[oauth-token-info]]
+=== OAuthTokenInfo
+The `OAuthTokenInfo` entity contains information about an OAuth access token.
+
+[options="header",cols="1,^1,5"]
+|========================
+|Field Name      ||Description
+|`username`      ||The owner of the OAuth access token.
+|`resource_host` ||The host of the Gerrit instance.
+|`access_token`  ||The actual token value.
+|`provider_id`   |optional|
+The identifier of the OAuth provider in the form `plugin-name:provider-name`.
+|`expires_at`    |optional|Time of expiration of this token in milliseconds.
+|`type`          ||The type of the OAuth access token, always `bearer`.
+|========================
+
 [[preferences-info]]
 === PreferencesInfo
 The `PreferencesInfo` entity contains information about a user's preferences.
@@ -1920,7 +2452,7 @@
 Whether the site header should be shown.
 |`use_flash_clipboard`          |not set if `false`|
 Whether to use the flash clipboard widget.
-|`download_scheme`              ||
+|`download_scheme`              |optional|
 The type of download URL the user prefers to use. May be any key from
 the `schemes` map in
 link:rest-api-config.html#download-info[DownloadInfo].
@@ -1942,6 +2474,9 @@
 Whether to show change number in the change table.
 |`mute_common_path_prefixes`    |not set if `false`|
 Whether to mute common path prefixes in file names in the file table.
+|`signed_off_by`                |not set if `false`|
+Whether to insert Signed-off-by footer in changes created with the
+inline edit feature.
 |`review_category_strategy`     ||
 The strategy used to displayed info in the review category column.
 Allowed values are `NONE`, `NAME`, `EMAIL`, `USERNAME`, `ABBREV`.
@@ -1954,6 +2489,12 @@
 |`url_aliases`                  |optional|
 A map of URL path pairs, where the first URL path is an alias for the
 second URL path.
+|`email_strategy`               ||
+The type of email strategy to use. On `ENABLED`, the user will receive emails
+from Gerrit. On `CC_ON_OWN_COMMENTS` the user will also receive emails for
+their own comments. On `DISABLED` the user will not receive any email
+notifications from Gerrit.
+Allowed values are `ENABLED`, `CC_ON_OWN_COMMENTS`, `DISABLED`.
 |============================================
 
 [[preferences-input]]
@@ -1991,6 +2532,9 @@
 Whether to show change number in the change table.
 |`mute_common_path_prefixes`    |optional|
 Whether to mute common path prefixes in file names in the file table.
+|`signed_off_by`                |optional|
+Whether to insert Signed-off-by footer in changes created with the
+inline edit feature.
 |`review_category_strategy`     |optional|
 The strategy used to displayed info in the review category column.
 Allowed values are `NONE`, `NAME`, `EMAIL`, `USERNAME`, `ABBREV`.
@@ -2003,6 +2547,12 @@
 |`url_aliases`                  |optional|
 A map of URL path pairs, where the first URL path is an alias for the
 second URL path.
+|`email_strategy`               |optional|
+The type of email strategy to use. On `ENABLED`, the user will receive emails
+from Gerrit. On `CC_ON_OWN_COMMENTS` the user will also receive emails for
+their own comments. On `DISABLED` the user will not receive any email
+notifications from Gerrit.
+Allowed values are `ENABLED`, `CC_ON_OWN_COMMENTS`, `DISABLED`.
 |============================================
 
 [[query-limit-info]]
@@ -2033,6 +2583,18 @@
 |`valid`         ||Whether the SSH key is valid.
 |=============================
 
+[[stars-input]]
+=== StarsInput
+The `StarsInput` entity contains star labels that should be added to
+or removed from a change.
+
+[options="header",cols="1,^1,5"]
+|========================
+|Field Name ||Description
+|`add`      |optional|List of labels to add to the change.
+|`remove`   |optional|List of labels to remove from the change.
+|========================
+
 [[username-input]]
 === UsernameInput
 The `UsernameInput` entity contains information for setting the
@@ -2044,6 +2606,22 @@
 |`username` |The new username of the account.
 |=======================
 
+[[project-watch-info]]
+=== ProjectWatchInfo
+The `WatchedProjectsInfo` entity contains information about a project watch
+for a user.
+
+[options="header",cols="1,^1,5"]
+|=======================
+|Field Name                 |        |Description
+|`project`                  |        |The name of the project.
+|`filter`                   |optional|A filter string to be applied to the project.
+|`notify_new_changes`       |optional|Notify on new changes.
+|`notify_new_patch_sets`    |optional|Notify on new patch sets.
+|`notify_all_comments`      |optional|Notify on comments.
+|`notify_submitted_changes` |optional|Notify on submitted changes.
+|`notify_abandoned_changes` |optional|Notify on abandoned changes.
+|=======================
 
 GERRIT
 ------
diff --git a/Documentation/rest-api-changes.txt b/Documentation/rest-api-changes.txt
index aa9417b..77feb18 100644
--- a/Documentation/rest-api-changes.txt
+++ b/Documentation/rest-api-changes.txt
@@ -13,10 +13,8 @@
 'POST /changes'
 --
 
-The change info link:#change-info[ChangeInfo] entity must be provided in the
-request body. Only the following attributes are honored: `project`,
-`branch`, `subject`, `status` and `topic`. The first three attributes are
-mandatory. Valid values for status are: `DRAFT` and `NEW`.
+The change input link:#change-input[ChangeInput] entity must be provided in the
+request body.
 
 .Request
 ----
@@ -130,8 +128,8 @@
   ]
 ----
 
-If the `n` query parameter is supplied and additional changes exist
-that match the query beyond the end, the last change object has a
+If the number of changes matching the query exceeds either the internal
+limit or a supplied `n` query parameter, the last change object has a
 `_more_changes: true` JSON field set.
 
 The `S` or `start` query parameter can be supplied to skip a number
@@ -194,6 +192,7 @@
 get::/changes/?q=is:open+owner:self&q=is:open+reviewer:self+-owner:self&q=is:closed+owner:self+limit:5&o=LABELS
 ****
 
+[[query-options]]
 Additional fields can be obtained by adding `o` parameters, each
 option requires more database lookups and slows down the query
 response time to the client so they are generally disabled by
@@ -209,8 +208,8 @@
 --
 * `DETAILED_LABELS`: detailed label information, including numeric
   values of all existing approvals, recognized label values, values
-  permitted to be set by the current user, and reviewers that may be
-  removed by the current user.
+  permitted to be set by the current user, all reviewers by state, and
+  reviewers that may be removed by the current user.
 --
 
 [[current-revision]]
@@ -266,6 +265,12 @@
   fields when referencing accounts.
 --
 
+[[reviewer-updates]]
+--
+* `REVIEWER_UPDATES`: include updates to reviewers set as
+  link:#review-update-info[ReviewerUpdateInfo] entities.
+--
+
 [[messages]]
 --
 * `MESSAGES`: include messages associated with the change.
@@ -355,6 +360,7 @@
       "current_revision": "184ebe53805e102605d11f6b143486d15c23a09c",
       "revisions": {
         "184ebe53805e102605d11f6b143486d15c23a09c": {
+          "kind": "REWORK",
           "_number": 1,
           "ref": "refs/changes/97/97/1",
           "fetch": {
@@ -414,35 +420,42 @@
           "files": {
             "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeCache.java": {
               "lines_deleted": 8,
-              "size_delta": -412
+              "size_delta": -412,
+              "size": 7782
             },
             "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeDetailCache.java": {
               "lines_inserted": 1,
-              "size_delta": 23
+              "size_delta": 23,
+              "size": 6762
             },
             "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeScreen.java": {
               "lines_inserted": 11,
               "lines_deleted": 19,
-              "size_delta": -298
+              "size_delta": -298,
+              "size": 47023
             },
             "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/ChangeTable.java": {
               "lines_inserted": 23,
               "lines_deleted": 20,
-              "size_delta": 132
+              "size_delta": 132,
+              "size": 17727
             },
             "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarCache.java": {
               "status": "D",
               "lines_deleted": 139,
-              "size_delta": -5512
+              "size_delta": -5512,
+              "size": 13098
             },
             "gerrit-gwtui/src/main/java/com/google/gerrit/client/changes/StarredChanges.java": {
               "status": "A",
               "lines_inserted": 204,
-              "size_delta": 8345
+              "size_delta": 8345,
+              "size": 8345
             },
             "gerrit-gwtui/src/main/java/com/google/gerrit/client/ui/Screen.java": {
               "lines_deleted": 9,
-              "size_delta": -343
+              "size_delta": -343,
+              "size": 5385
             }
           }
         }
@@ -505,8 +518,8 @@
 --
 
 Retrieves a change with link:#labels[labels], link:#detailed-labels[
-detailed labels], link:#detailed-accounts[detailed accounts], and
-link:#messages[messages].
+detailed labels], link:#detailed-accounts[detailed accounts],
+link:#reviewer-updates[reviewer updates], and link:#messages[messages].
 
 Additional fields can be obtained by adding `o` parameters, each
 option requires more database lookups and slows down the query
@@ -634,6 +647,72 @@
         "username": "jroe"
       }
     ],
+    "reviewers": {
+      "REVIEWER": [
+        {
+          "_account_id": 1000096,
+          "name": "John Doe",
+          "email": "john.doe@example.com",
+          "username": "jdoe"
+        },
+        {
+          "_account_id": 1000097,
+          "name": "Jane Roe",
+          "email": "jane.roe@example.com",
+          "username": "jroe"
+        }
+      ]
+    },
+    "reviewer_updates": [
+      {
+        "state": "REVIEWER",
+        "reviewer": {
+          "_account_id": 1000096,
+          "name": "John Doe",
+          "email": "john.doe@example.com",
+          "username": "jdoe"
+        },
+        "updated_by": {
+          "_account_id": 1000096,
+          "name": "John Doe",
+          "email": "john.doe@example.com",
+          "username": "jdoe"
+        },
+        "updated": "2016-07-21 20:12:39.000000000"
+      },
+      {
+        "state": "REMOVED",
+        "reviewer": {
+          "_account_id": 1000096,
+          "name": "John Doe",
+          "email": "john.doe@example.com",
+          "username": "jdoe"
+        },
+        "updated_by": {
+          "_account_id": 1000096,
+          "name": "John Doe",
+          "email": "john.doe@example.com",
+          "username": "jdoe"
+        },
+        "updated": "2016-07-21 20:12:33.000000000"
+      },
+      {
+        "state": "CC",
+        "reviewer": {
+          "_account_id": 1000096,
+          "name": "John Doe",
+          "email": "john.doe@example.com",
+          "username": "jdoe"
+        },
+        "updated_by": {
+          "_account_id": 1000096,
+          "name": "John Doe",
+          "email": "john.doe@example.com",
+          "username": "jdoe"
+        },
+        "updated": "2016-03-23 21:34:02.419000000",
+      },
+    ],
     "messages": [
       {
         "id": "YH-egE",
@@ -912,6 +991,7 @@
     "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822",
     "revisions": {
       "27cc4558b5a3d3387dd11ee2df7a117e7e581822": {
+        "kind": "REWORK",
         "_number": 2,
         "ref": "refs/changes/99/4799/2",
         "fetch": {
@@ -959,6 +1039,84 @@
   The change could not be rebased due to a path conflict during merge.
 ----
 
+[[move-change]]
+=== Move Change
+--
+'POST /changes/link:#change-id[\{change-id\}]/move'
+--
+
+Move a change.
+
+The destination branch must be provided in the request body inside a
+link:#move-input[MoveInput] entity.
+
+.Request
+----
+  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/move HTTP/1.0
+  Content-Type: application/json; charset=UTF-8
+
+  {
+    "destination_branch" : "release-branch"
+  }
+
+----
+
+As response a link:#change-info[ChangeInfo] entity is returned that
+describes the moved change.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "id": "myProject~release-branch~I8473b95934b5732ac55d26311a706c9c2bde9940",
+    "project": "myProject",
+    "branch": "release-branch",
+    "change_id": "I8473b95934b5732ac55d26311a706c9c2bde9940",
+    "subject": "Implementing Feature X",
+    "status": "NEW",
+    "created": "2013-02-01 09:59:32.126000000",
+    "updated": "2013-02-21 11:16:36.775000000",
+    "mergeable": true,
+    "insertions": 2,
+    "deletions": 13,
+    "_number": 3965,
+    "owner": {
+      "name": "John Doe"
+    }
+  }
+----
+
+If the change cannot be moved because the change state doesn't
+allow moving the change, the response is "`409 Conflict`" and
+the error message is contained in the response body.
+
+.Response
+----
+  HTTP/1.1 409 Conflict
+  Content-Disposition: attachment
+  Content-Type: text/plain; charset=UTF-8
+
+  change is merged
+----
+
+If the change cannot be moved because the user doesn't have
+abandon permission on the change or upload permission on the destination,
+the response is "`409 Conflict`" and the error message is contained in the
+response body.
+
+.Response
+----
+  HTTP/1.1 409 Conflict
+  Content-Disposition: attachment
+  Content-Type: text/plain; charset=UTF-8
+
+  move not permitted
+----
+
 [[revert-change]]
 === Revert Change
 --
@@ -972,7 +1130,7 @@
 
 .Request
 ----
-  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revert HTTP/1.0
+  POST /changes/myProject~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14/revert HTTP/1.0
 ----
 
 As response a link:#change-info[ChangeInfo] entity is returned that
@@ -1026,8 +1184,7 @@
 Submits a change.
 
 The request body only needs to include a link:#submit-input[
-SubmitInput] entity if the request should wait for the merge to
-complete.
+SubmitInput] entity if submitting on behalf of another user.
 
 .Request
 ----
@@ -1035,7 +1192,7 @@
   Content-Type: application/json; charset=UTF-8
 
   {
-    "wait_for_merge": true
+    "on_behalf_of": 1001439
   }
 ----
 
@@ -1058,6 +1215,7 @@
     "status": "MERGED",
     "created": "2013-02-01 09:59:32.126000000",
     "updated": "2013-02-21 11:16:36.775000000",
+    "submitted": "2013-02-21 11:16:36.615000000",
     "_number": 3965,
     "owner": {
       "name": "John Doe"
@@ -1079,29 +1237,15 @@
 ----
 
 [[submitted-together]]
-=== Changes submitted together
+=== Changes Submitted Together
 --
-'GET /changes/link:#change-id[\{change-id\}]/submitted_together'
+'GET /changes/link:#change-id[\{change-id\}]/submitted_together?o=NON_VISIBLE_CHANGES'
 --
 
-Returns a list of all changes which are submitted when
-link:#submit-change[\{submit\}] is called for this change,
+Computes list of all changes which are submitted when
+link:#submit-change[Submit] is called for this change,
 including the current change itself.
 
-An empty list is returned if this change will be submitted
-by itself (no other changes).
-
-.Request
-----
-  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/submitted_together HTTP/1.0
-  Content-Type: application/json; charset=UTF-8
-----
-
-The return value is a list of changes in the same format as in
-link:#list-changes[\{listing changes\}] with the options
-link:#labels[\{LABELS\}], link:#detailed-labels[\{DETAILED_LABELS\}],
-link:#current-revision[\{CURRENT_REVISION\}],
-link:#current-commit[\{CURRENT_COMMIT\}] set.
 The list consists of:
 
 * The given change.
@@ -1110,6 +1254,27 @@
 * For each change whose submit type is not CHERRY_PICK, include unmerged
   ancestors targeting the same branch.
 
+As a special case, the list is empty if this change would be
+submitted by itself (without other changes).
+
+.Request
+----
+  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/submitted_together?o=NON_VISIBLE_CHANGES HTTP/1.0
+  Content-Type: application/json; charset=UTF-8
+----
+
+As a response a link:#submitted-together-info[SubmittedTogetherInfo]
+entity is returned that describes what would happen if the change were
+submitted. This response contains a list of changes and a count of
+changes that are not visible to the caller that are part of the set of
+changes to be merged.
+
+The listed changes use the same format as in
+link:#list-changes[Query Changes] with the
+link:#labels[`LABELS`], link:#detailed-labels[`DETAILED_LABELS`],
+link:#current-revision[`CURRENT_REVISION`], and
+link:#current-commit[`CURRENT_COMMIT`] options set.
+
 .Response
 ----
   HTTP/1.1 200 OK
@@ -1117,232 +1282,257 @@
   Content-Type: application/json; charset=UTF-8
 
 )]}'
-[
-  {
-    "id": "gerrit~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14",
-    "project": "gerrit",
-    "branch": "master",
-    "hashtags": [],
-    "change_id": "I1ffe09a505e25f15ce1521bcfb222e51e62c2a14",
-    "subject": "ChangeMergeQueue: Rewrite such that it works on set of changes",
-    "status": "NEW",
-    "created": "2015-05-01 15:39:57.979000000",
-    "updated": "2015-05-20 19:25:21.592000000",
-    "mergeable": true,
-    "insertions": 303,
-    "deletions": 210,
-    "_number": 1779,
-    "owner": {
-      "_account_id": 1000000
-    },
-    "labels": {
-      "Code-Review": {
-        "approved": {
-          "_account_id": 1000000
-        },
-        "all": [
-          {
-            "value": 2,
-            "date": "2015-05-20 19:25:21.592000000",
-            "_account_id": 1000000
-          }
-        ],
-        "values": {
-          "-2": "This shall not be merged",
-          "-1": "I would prefer this is not merged as is",
-          " 0": "No score",
-          "+1": "Looks good to me, but someone else must approve",
-          "+2": "Looks good to me, approved"
-        },
-        "default_value": 0
-      },
-      "Verified": {
-        "approved": {
-          "_account_id": 1000000
-        },
-        "all": [
-          {
-            "value": 1,
-            "date": "2015-05-20 19:25:21.592000000",
-            "_account_id": 1000000
-          }
-        ],
-        "values": {
-          "-1": "Fails",
-          " 0": "No score",
-          "+1": "Verified"
-        },
-        "default_value": 0
-      }
-    },
-    "permitted_labels": {
-      "Code-Review": [
-        "-2",
-        "-1",
-        " 0",
-        "+1",
-        "+2"
-      ],
-      "Verified": [
-        "-1",
-        " 0",
-        "+1"
-      ]
-    },
-    "removable_reviewers": [
-      {
+{
+  "changes": [
+    {
+      "id": "gerrit~master~I1ffe09a505e25f15ce1521bcfb222e51e62c2a14",
+      "project": "gerrit",
+      "branch": "master",
+      "hashtags": [],
+      "change_id": "I1ffe09a505e25f15ce1521bcfb222e51e62c2a14",
+      "subject": "ChangeMergeQueue: Rewrite such that it works on set of changes",
+      "status": "NEW",
+      "created": "2015-05-01 15:39:57.979000000",
+      "updated": "2015-05-20 19:25:21.592000000",
+      "mergeable": true,
+      "insertions": 303,
+      "deletions": 210,
+      "_number": 1779,
+      "owner": {
         "_account_id": 1000000
-      }
-    ],
-    "current_revision": "9adb9f4c7b40eeee0646e235de818d09164d7379",
-    "revisions": {
-      "9adb9f4c7b40eeee0646e235de818d09164d7379": {
-        "_number": 1,
-        "created": "2015-05-01 15:39:57.979000000",
-        "uploader": {
-          "_account_id": 1000000
-        },
-        "ref": "refs/changes/79/1779/1",
-        "fetch": {},
-        "commit": {
-          "parents": [
+      },
+      "labels": {
+        "Code-Review": {
+          "approved": {
+            "_account_id": 1000000
+          },
+          "all": [
             {
-              "commit": "2d3176497a2747faed075f163707e57d9f961a1c",
-              "subject": "Merge changes from topic \u0027submodule-subscription-tests-and-fixes-3\u0027"
+              "value": 2,
+              "date": "2015-05-20 19:25:21.592000000",
+              "_account_id": 1000000
             }
           ],
-          "author": {
-            "name": "Stefan Beller",
-            "email": "sbeller@google.com",
-            "date": "2015-04-29 21:36:52.000000000",
-            "tz": -420
+          "values": {
+            "-2": "This shall not be merged",
+            "-1": "I would prefer this is not merged as is",
+            " 0": "No score",
+            "+1": "Looks good to me, but someone else must approve",
+            "+2": "Looks good to me, approved"
           },
-          "committer": {
-            "name": "Stefan Beller",
-            "email": "sbeller@google.com",
-            "date": "2015-05-01 00:11:16.000000000",
-            "tz": -420
+          "default_value": 0
+        },
+        "Verified": {
+          "approved": {
+            "_account_id": 1000000
           },
-          "subject": "ChangeMergeQueue: Rewrite such that it works on set of changes",
-          "message": "ChangeMergeQueue: Rewrite such that it works on set of changes\n\nChangeMergeQueue used to work on branches rather than sets of changes.\nThis change is a first step to merge sets of changes (e.g. grouped by a\ntopic and `changes.submitWholeTopic` enabled) in an atomic fashion.\nThis change doesn\u0027t aim to implement these changes, but only as a step\ntowards it.\n\nMergeOp keeps its functionality and behavior as is. A new class\nMergeOpMapper is introduced which will map the set of changes to\nthe set of branches. Additionally the MergeOpMapper is also\nresponsible for the threading done right now, which was part of\nthe ChangeMergeQueue before.\n\nChange-Id: I1ffe09a505e25f15ce1521bcfb222e51e62c2a14\n"
+          "all": [
+            {
+              "value": 1,
+              "date": "2015-05-20 19:25:21.592000000",
+              "_account_id": 1000000
+            }
+          ],
+          "values": {
+            "-1": "Fails",
+            " 0": "No score",
+            "+1": "Verified"
+          },
+          "default_value": 0
+        }
+      },
+      "permitted_labels": {
+        "Code-Review": [
+          "-2",
+          "-1",
+          " 0",
+          "+1",
+          "+2"
+        ],
+        "Verified": [
+          "-1",
+          " 0",
+          "+1"
+        ]
+      },
+      "removable_reviewers": [
+        {
+          "_account_id": 1000000
+        }
+      ],
+      "reviewers": {
+        "REVIEWER": [
+          {
+            "_account_id": 1000000
+          }
+        ]
+      },
+      "current_revision": "9adb9f4c7b40eeee0646e235de818d09164d7379",
+      "revisions": {
+        "9adb9f4c7b40eeee0646e235de818d09164d7379": {
+          "kind": "REWORK",
+          "_number": 1,
+          "created": "2015-05-01 15:39:57.979000000",
+          "uploader": {
+            "_account_id": 1000000
+          },
+          "ref": "refs/changes/79/1779/1",
+          "fetch": {},
+          "commit": {
+            "parents": [
+              {
+                "commit": "2d3176497a2747faed075f163707e57d9f961a1c",
+                "subject": "Merge changes from topic \u0027submodule-subscription-tests-and-fixes-3\u0027"
+              }
+            ],
+            "author": {
+              "name": "Stefan Beller",
+              "email": "sbeller@google.com",
+              "date": "2015-04-29 21:36:52.000000000",
+              "tz": -420
+            },
+            "committer": {
+              "name": "Stefan Beller",
+              "email": "sbeller@google.com",
+              "date": "2015-05-01 00:11:16.000000000",
+              "tz": -420
+            },
+            "subject": "ChangeMergeQueue: Rewrite such that it works on set of changes",
+            "message": "ChangeMergeQueue: Rewrite such that it works on set of changes\n\nChangeMergeQueue used to work on branches rather than sets of changes.\nThis change is a first step to merge sets of changes (e.g. grouped by a\ntopic and `changes.submitWholeTopic` enabled) in an atomic fashion.\nThis change doesn\u0027t aim to implement these changes, but only as a step\ntowards it.\n\nMergeOp keeps its functionality and behavior as is. A new class\nMergeOpMapper is introduced which will map the set of changes to\nthe set of branches. Additionally the MergeOpMapper is also\nresponsible for the threading done right now, which was part of\nthe ChangeMergeQueue before.\n\nChange-Id: I1ffe09a505e25f15ce1521bcfb222e51e62c2a14\n"
+          }
+        }
+      }
+    },
+    {
+      "id": "gerrit~master~I7fe807e63792b3d26776fd1422e5e790a5697e22",
+      "project": "gerrit",
+      "branch": "master",
+      "hashtags": [],
+      "change_id": "I7fe807e63792b3d26776fd1422e5e790a5697e22",
+      "subject": "AbstractSubmoduleSubscription: Split up createSubscription",
+      "status": "NEW",
+      "created": "2015-05-01 15:39:57.979000000",
+      "updated": "2015-05-20 19:25:21.546000000",
+      "mergeable": true,
+      "insertions": 15,
+      "deletions": 6,
+      "_number": 1780,
+      "owner": {
+        "_account_id": 1000000
+      },
+      "labels": {
+        "Code-Review": {
+          "approved": {
+            "_account_id": 1000000
+          },
+          "all": [
+            {
+              "value": 2,
+              "date": "2015-05-20 19:25:21.546000000",
+              "_account_id": 1000000
+            }
+          ],
+          "values": {
+            "-2": "This shall not be merged",
+            "-1": "I would prefer this is not merged as is",
+            " 0": "No score",
+            "+1": "Looks good to me, but someone else must approve",
+            "+2": "Looks good to me, approved"
+          },
+          "default_value": 0
+        },
+        "Verified": {
+          "approved": {
+            "_account_id": 1000000
+          },
+          "all": [
+            {
+              "value": 1,
+              "date": "2015-05-20 19:25:21.546000000",
+              "_account_id": 1000000
+            }
+          ],
+          "values": {
+            "-1": "Fails",
+            " 0": "No score",
+            "+1": "Verified"
+          },
+          "default_value": 0
+        }
+      },
+      "permitted_labels": {
+        "Code-Review": [
+          "-2",
+          "-1",
+          " 0",
+          "+1",
+          "+2"
+        ],
+        "Verified": [
+          "-1",
+          " 0",
+          "+1"
+        ]
+      },
+      "removable_reviewers": [
+        {
+          "_account_id": 1000000
+        }
+      ],
+      "reviewers": {
+        "REVIEWER": [
+          {
+            "_account_id": 1000000
+          }
+        ]
+      },
+      "current_revision": "1bd7c12a38854a2c6de426feec28800623f492c4",
+      "revisions": {
+        "1bd7c12a38854a2c6de426feec28800623f492c4": {
+          "kind": "REWORK",
+          "_number": 1,
+          "created": "2015-05-01 15:39:57.979000000",
+          "uploader": {
+            "_account_id": 1000000
+          },
+          "ref": "refs/changes/80/1780/1",
+          "fetch": {},
+          "commit": {
+            "parents": [
+              {
+                "commit": "9adb9f4c7b40eeee0646e235de818d09164d7379",
+                "subject": "ChangeMergeQueue: Rewrite such that it works on set of changes"
+              }
+            ],
+            "author": {
+              "name": "Stefan Beller",
+              "email": "sbeller@google.com",
+              "date": "2015-04-25 00:11:59.000000000",
+              "tz": -420
+            },
+            "committer": {
+              "name": "Stefan Beller",
+              "email": "sbeller@google.com",
+              "date": "2015-05-01 00:11:16.000000000",
+              "tz": -420
+            },
+            "subject": "AbstractSubmoduleSubscription: Split up createSubscription",
+            "message": "AbstractSubmoduleSubscription: Split up createSubscription\n\nLater we want to have subscriptions to more submodules, so we need to\nfind a way to add more submodule entries into the file. By splitting up\nthe createSubscription() method, that is very easy by using the\naddSubmoduleSubscription method multiple times.\n\nChange-Id: I7fe807e63792b3d26776fd1422e5e790a5697e22\n"
+          }
         }
       }
     }
-  },
-  {
-    "id": "gerrit~master~I7fe807e63792b3d26776fd1422e5e790a5697e22",
-    "project": "gerrit",
-    "branch": "master",
-    "hashtags": [],
-    "change_id": "I7fe807e63792b3d26776fd1422e5e790a5697e22",
-    "subject": "AbstractSubmoduleSubscription: Split up createSubscription",
-    "status": "NEW",
-    "created": "2015-05-01 15:39:57.979000000",
-    "updated": "2015-05-20 19:25:21.546000000",
-    "mergeable": true,
-    "insertions": 15,
-    "deletions": 6,
-    "_number": 1780,
-    "owner": {
-      "_account_id": 1000000
-    },
-    "labels": {
-      "Code-Review": {
-        "approved": {
-          "_account_id": 1000000
-        },
-        "all": [
-          {
-            "value": 2,
-            "date": "2015-05-20 19:25:21.546000000",
-            "_account_id": 1000000
-          }
-        ],
-        "values": {
-          "-2": "This shall not be merged",
-          "-1": "I would prefer this is not merged as is",
-          " 0": "No score",
-          "+1": "Looks good to me, but someone else must approve",
-          "+2": "Looks good to me, approved"
-        },
-        "default_value": 0
-      },
-      "Verified": {
-        "approved": {
-          "_account_id": 1000000
-        },
-        "all": [
-          {
-            "value": 1,
-            "date": "2015-05-20 19:25:21.546000000",
-            "_account_id": 1000000
-          }
-        ],
-        "values": {
-          "-1": "Fails",
-          " 0": "No score",
-          "+1": "Verified"
-        },
-        "default_value": 0
-      }
-    },
-    "permitted_labels": {
-      "Code-Review": [
-        "-2",
-        "-1",
-        " 0",
-        "+1",
-        "+2"
-      ],
-      "Verified": [
-        "-1",
-        " 0",
-        "+1"
-      ]
-    },
-    "removable_reviewers": [
-      {
-        "_account_id": 1000000
-      }
-    ],
-    "current_revision": "1bd7c12a38854a2c6de426feec28800623f492c4",
-    "revisions": {
-      "1bd7c12a38854a2c6de426feec28800623f492c4": {
-        "_number": 1,
-        "created": "2015-05-01 15:39:57.979000000",
-        "uploader": {
-          "_account_id": 1000000
-        },
-        "ref": "refs/changes/80/1780/1",
-        "fetch": {},
-        "commit": {
-          "parents": [
-            {
-              "commit": "9adb9f4c7b40eeee0646e235de818d09164d7379",
-              "subject": "ChangeMergeQueue: Rewrite such that it works on set of changes"
-            }
-          ],
-          "author": {
-            "name": "Stefan Beller",
-            "email": "sbeller@google.com",
-            "date": "2015-04-25 00:11:59.000000000",
-            "tz": -420
-          },
-          "committer": {
-            "name": "Stefan Beller",
-            "email": "sbeller@google.com",
-            "date": "2015-05-01 00:11:16.000000000",
-            "tz": -420
-          },
-          "subject": "AbstractSubmoduleSubscription: Split up createSubscription",
-          "message": "AbstractSubmoduleSubscription: Split up createSubscription\n\nLater we want to have subscriptions to more submodules, so we need to\nfind a way to add more submodule entries into the file. By splitting up\nthe createSubscription() method, that is very easy by using the\naddSubmoduleSubscription method multiple times.\n\nChange-Id: I7fe807e63792b3d26776fd1422e5e790a5697e22\n"
-        }
-      }
-    }
-  }
-]
+  ],
+  "non_visible_changes": 0
+}
 ----
 
+If the `o=NON_VISIBLE_CHANGES` query parameter is not passed, then
+instead of a link:#submitted-together-info[SubmittedTogetherInfo]
+entity, the response is a list of changes, or a 403 response with a
+message if the set of changes to be submitted with this change
+includes changes the caller cannot read.
+
 
 [[publish-draft-change]]
 === Publish Draft Change
@@ -1533,7 +1723,7 @@
 ----
 
 [[check-change]]
-=== Check change
+=== Check Change
 --
 'GET /changes/link:#change-id[\{change-id\}]/check'
 --
@@ -1583,7 +1773,7 @@
 ----
 
 [[fix-change]]
-=== Fix change
+=== Fix Change
 --
 'POST /changes/link:#change-id[\{change-id\}]/check'
 --
@@ -1618,6 +1808,7 @@
     "status": "MERGED",
     "created": "2013-02-01 09:59:32.126000000",
     "updated": "2013-02-21 11:16:36.775000000",
+    "submitted": "2013-02-21 11:16:36.615000000",
     "mergeable": true,
     "insertions": 34,
     "deletions": 101,
@@ -1692,6 +1883,7 @@
        "subject":"Use an EventBus to manage star icons",
        "message":"Use an EventBus to manage star icons\n\nImage widgets that need to ..."
     },
+    "base_revision":"c35558e0925e6985c91f3a16921537d5e572b7a3"
   }
 ----
 
@@ -1835,6 +2027,9 @@
 If only the content type is required, callers should use HEAD to
 avoid downloading the encoded file contents.
 
+If the `base` parameter is set to true, the returned content is from the
+revision that the edit is based on.
+
 .Response
 ----
   HTTP/1.1 200 OK
@@ -1902,6 +2097,9 @@
 
 Retrieves commit message from change edit.
 
+If the `base` parameter is set to true, the returned message is from the
+revision that the edit is based on.
+
 .Request
 ----
   GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/edit:message HTTP/1.0
@@ -2068,13 +2266,15 @@
         "_account_id": 1000097,
         "name": "Jane Roe",
         "email": "jane.roe@example.com"
-      }
+      },
+      "count": 1
     },
     {
       "group": {
         "id": "4fd581c0657268f2bdcc26699fbf9ddb76e3a279",
         "name": "Joiner"
-      }
+      },
+      "count": 5
     }
   ]
 ----
@@ -2147,6 +2347,7 @@
   {
     "reviewers": [
       {
+        "input": "john.doe@example.com",
         "approvals": {
           "Verified": " 0",
           "Code-Review": " 0"
@@ -2184,6 +2385,7 @@
 
   )]}'
   {
+    "input": "MyProjectVerifiers",
     "error": "The group My Group has 15 members. Do you want to add them all as reviewers?",
     "confirm": true
   }
@@ -2198,7 +2400,7 @@
   Content-Type: application/json; charset=UTF-8
 
   {
-    "reviewer": "MyProjectVerifiers",
+    "input": "MyProjectVerifiers",
     "confirmed": true
   }
 ----
@@ -2221,6 +2423,74 @@
   HTTP/1.1 204 No Content
 ----
 
+[[list-votes]]
+=== List Votes
+--
+'GET /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/'
+--
+
+Lists the votes for a specific reviewer of the change.
+
+.Request
+----
+  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/ HTTP/1.0
+----
+
+As result a map is returned that maps the label name to the label value.
+The entries in the map are sorted by label name.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json;charset=UTF-8
+
+  )]}'
+  {
+    "Code-Review": -1,
+    "Verified": 1
+    "Work-In-Progress": 1,
+  }
+----
+
+[[delete-vote]]
+=== Delete Vote
+--
+'DELETE /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/link:#label-id[\{label-id\}]'
+'POST /changes/link:#change-id[\{change-id\}]/reviewers/link:rest-api-accounts.html#account-id[\{account-id\}]/votes/link:#label-id[\{label-id\}]/delete'
+--
+
+Deletes a single vote from a change. Note, that even when the last vote of
+a reviewer is removed the reviewer itself is still listed on the change.
+
+Options can be provided in the request body as a
+link:#delete-vote-input[DeleteVoteInput] entity.
+
+.Request
+----
+  DELETE /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review HTTP/1.0
+  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0
+----
+
+Please note that some proxies prohibit request bodies for DELETE
+requests. In this case, if you want to specify options, use a POST
+request:
+
+.Request
+----
+  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/reviewers/John%20Doe/votes/Code-Review/delete HTTP/1.0
+  Content-Type: application/json; charset=UTF-8
+
+  {
+    "notify": "NONE"
+  }
+----
+
+.Response
+----
+  HTTP/1.1 204 No Content
+----
+
 [[revision-endpoints]]
 == Revision Endpoints
 
@@ -2434,15 +2704,31 @@
         "email": "jane.roe@example.com"
       }
     ],
+    "reviewers": {
+      "REVIEWER": [
+        {
+          "_account_id": 1000096,
+          "name": "John Doe",
+          "email": "john.doe@example.com"
+        },
+        {
+          "_account_id": 1000097,
+          "name": "Jane Roe",
+          "email": "jane.roe@example.com"
+        }
+      ]
+    },
     "current_revision": "674ac754f91e64a0efb8087e59a176484bd534d1",
     "revisions": {
       "674ac754f91e64a0efb8087e59a176484bd534d1": {
-      "_number": 2,
-      "ref": "refs/changes/65/3965/2",
-      "fetch": {
-        "http": {
-          "url": "http://gerrit/myProject",
-          "ref": "refs/changes/65/3965/2"
+        "kind": "REWORK",
+        "_number": 2,
+        "ref": "refs/changes/65/3965/2",
+        "fetch": {
+          "http": {
+            "url": "http://gerrit/myProject",
+            "ref": "refs/changes/65/3965/2"
+          }
         }
       }
     }
@@ -2541,6 +2827,7 @@
   Content-Type: application/json; charset=UTF-8
 
   {
+    "tag": "jenkins",
     "message": "Some nits need to be fixed.",
     "labels": {
       "Code-Review": -1
@@ -2589,6 +2876,92 @@
 A review cannot be set on a change edit. Trying to post a review for a
 change edit fails with `409 Conflict`.
 
+It is also possible to add one or more reviewers to a change simultaneously
+with a review.
+
+.Request
+----
+  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/review HTTP/1.0
+  Content-Type: application/json; charset=UTF-8
+
+  {
+    "message": "Looks good to me, but Jane and John should also take a look.",
+    "labels": {
+      "Code-Review": 1
+    },
+    "reviewers": [
+      {
+        "reviewer": "jane.roe@example.com"
+      },
+      {
+        "reviewer": "john.doe@example.com"
+      }
+    ]
+  }
+----
+
+Each element of the `reviewers` list is an instance of
+link:#reviewer-input[ReviewerInput]. The corresponding result of
+adding each reviewer will be returned in a list of
+link:#add-reviewer-result[AddReviewerResult].
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "labels": {
+      "Code-Review": 1
+    },
+    "reviewers": [
+      {
+        "input": "jane.roe@example.com",
+        "approvals": {
+          "Verified": " 0",
+          "Code-Review": " 0"
+        },
+        "_account_id": 1000097,
+        "name": "Jane Roe",
+        "email": "jane.roe@example.com"
+      },
+      {
+        "input": "john.doe@example.com",
+        "approvals": {
+          "Verified": " 0",
+          "Code-Review": " 0"
+        },
+        "_account_id": 1000096,
+        "name": "John Doe",
+        "email": "john.doe@example.com"
+      }
+    ]
+  }
+----
+
+If there are any errors returned for reviewers, the entire review request will
+be rejected with `400 Bad Request`.
+
+.Error Response
+----
+  HTTP/1.1 400 Bad Request
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "reviewers": {
+      "MyProjectVerifiers": {
+        "input": "MyProjectVerifiers",
+        "error": "The group My Group has 15 members. Do you want to add them all as reviewers?",
+        "confirm": true
+      }
+    }
+  }
+----
+
 [[rebase-revision]]
 === Rebase Revision
 --
@@ -2640,6 +3013,7 @@
     "current_revision": "27cc4558b5a3d3387dd11ee2df7a117e7e581822",
     "revisions": {
       "27cc4558b5a3d3387dd11ee2df7a117e7e581822": {
+        "kind": "REWORK",
         "_number": 2,
         "ref": "refs/changes/99/4799/2",
         "fetch": {
@@ -2827,7 +3201,8 @@
   )]}'
   {
     submit_type: "MERGE_IF_NECESSARY",
-    mergeable: true,
+    strategy: "recursive",
+    mergeable: true
   }
 ----
 
@@ -3264,12 +3639,14 @@
     "/COMMIT_MSG": {
       "status": "A",
       "lines_inserted": 7,
-      "size_delta": 551
+      "size_delta": 551,
+      "size": 551
     },
     "gerrit-server/src/main/java/com/google/gerrit/server/project/RefControl.java": {
       "lines_inserted": 5,
       "lines_deleted": 3,
-      "size_delta": 98
+      "size_delta": 98,
+      "size": 23348
     }
   }
 ----
@@ -3283,6 +3660,11 @@
 in the path name. This is useful to implement suggestion services
 finding a file by partial name.
 
+The integer-valued request parameter `parent` changes the response to return a
+list of the files which are different in this commit compared to the given
+parent commit. This is useful for supporting review of merge commits.  The value
+is the 1-based index of the parent's position in the commit object.
+
 .Request
 ----
   GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/?reviewed HTTP/1.0
@@ -3368,7 +3750,7 @@
 
 .Request
 ----
-  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/website%2Freleases%2Flogo.png/safe_content HTTP/1.0
+  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/website%2Freleases%2Flogo.png/download HTTP/1.0
 ----
 
 .Response
@@ -3382,7 +3764,7 @@
 
 .Request
 ----
-  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/safe_content?suffix=new HTTP/1.0
+  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/download?suffix=new HTTP/1.0
 ----
 
 .Response
@@ -3528,6 +3910,11 @@
 The `base` parameter can be specified to control the base patch set from which the diff should
 be generated.
 
+The integer-valued request parameter `parent` can be specified to control the
+parent commit number against which the diff should be generated.  This is useful
+for supporting review of merge commits.  The value is the 1-based index of the
+parent's position in the commit object.
+
 [[weblinks-only]]
 If the `weblinks-only` parameter is specified, only the diff web links are returned.
 
@@ -3563,12 +3950,73 @@
   }
 ----
 
-The `ignore-whitespace` parameter can be specified to control how whitespace differences are
-reported in the result.  Valid values are `NONE`, `TRAILING`, `CHANGED` or `ALL`.
+The `whitespace` parameter can be specified to control how whitespace
+differences are reported in the result.  Valid values are `IGNORE_NONE`,
+`IGNORE_TRAILING`, `IGNORE_LEADING_AND_TRAILING` or `IGNORE_ALL`.
 
 The `context` parameter can be specified to control the number of lines of surrounding context
 in the diff.  Valid values are `ALL` or number of lines.
 
+[[get-blame]]
+=== Get Blame
+--
+'GET /changes/link:#change-id[\{change-id\}]/revisions/link:#revision-id[\{revision-id\}]/files/link:#file-id[\{file-id\}]/blame'
+--
+
+Gets the blame of a file from a certain revision.
+
+.Request
+----
+  GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/revisions/674ac754f91e64a0efb8087e59a176484bd534d1/files/gerrit-server%2Fsrc%2Fmain%2Fjava%2Fcom%2Fgoogle%2Fgerrit%2Fserver%2Fproject%2FRefControl.java/blame HTTP/1.0
+----
+
+As response a link:#blame-info[BlameInfo] entity is returned that describes the
+blame.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]
+  {
+    [
+      {
+        "author": "Joe Daw",
+        "id": "64e140b4de5883a4dd74d06c2b62ccd7ffd224a7",
+        "time": 1421441349,
+        "commit_msg": "RST test\n\nChange-Id: I11e9e24bd122253f4bb10c36dce825ac2410d646\n",
+        "ranges": [
+          {
+            "start": 1,
+            "end": 10
+          },
+          {
+            "start": 16,
+            "end": 296
+          }
+        ]
+      },
+      {
+        "author": "Jane Daw",
+        "id": "8d52621a0e2ac6adec73bd3a49f2371cd53137a7",
+        "time": 1421825421,
+        "commit_msg": "add banner\n\nChange-Id: I2eced9b2691015ae3c5138f4d0c4ca2b8fb15be9\n",
+        "ranges": [
+          {
+            "start": 13,
+            "end": 13
+          }
+        ]
+      }
+    ]
+  }
+----
+
+The `base` parameter can be specified to control the base patch set from which
+the blame should be generated.
+
 [[set-reviewed]]
 === Set Reviewed
 --
@@ -3688,6 +4136,10 @@
 === \{draft-id\}
 UUID of a draft comment.
 
+[[label-id]]
+=== \{label-id\}
+The name of the label.
+
 [[file-id]]
 \{file-id\}
 ~~~~~~~~~~~~
@@ -3704,6 +4156,7 @@
 * an abbreviated commit ID that uniquely identifies one revision of the
   change ("674ac754"), at least 4 digits are required
 * a legacy numeric patch number ("1" for first patch set of the change)
+* "0" or the literal `edit` for a change edit
 
 [[json-entities]]
 == JSON Entities
@@ -3718,6 +4171,11 @@
 |`message`     |optional|
 Message to be added as review comment to the change when abandoning the
 change.
+|`notify`      |optional|
+Notify handling that defines to whom email notifications should be sent after
+the change is abandoned. +
+Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
+If not set, the default is `ALL`.
 |===========================
 
 [[action-info]]
@@ -3754,9 +4212,17 @@
 [options="header",cols="1,^1,5"]
 |===========================
 |Field Name    ||Description
+|`input`    ||
+Value of the `reviewer` field from link:#reviewer-input[ReviewerInput]
+set while adding the reviewer.
 |`reviewers`   |optional|
 The newly added reviewers as a list of link:#reviewer-info[
 ReviewerInfo] entities.
+|`ccs`         |optional|
+The newly CCed accounts as a list of link:#reviewer-info[
+ReviewerInfo] entities. This field will only appear if the requested
+`state` for the reviewer was `CC` *and* NoteDb is enabled on the
+server.
 |`error`       |optional|
 Error message explaining why the reviewer could not be added. +
 If a group was specified in the input and an error is returned, it
@@ -3783,6 +4249,27 @@
 permitted to vote on that label.
 |`date`        |optional|
 The time and date describing when the approval was made.
+|`tag`                 |optional|
+Value of the `tag` field from link:#review-input[ReviewInput] set
+while posting the review.
+NOTE: To apply different tags on on different votes/comments multiple
+invocations of the REST call are required.
+|===========================
+
+[[blame-info]]
+=== BlameInfo
+The `BlameInfo` entity stores the commit metadata with the row coordinates where
+it applies.
+
+[options="header",cols="1,6"]
+|===========================
+|Field Name | Description
+|`author`     | The author of the commit.
+|`id`         | The id of the commit.
+|`time`       | Commit time.
+|`commit_msg` | The commit message.
+|`ranges`     |
+The blame row coordinates as link:#range-info[RangeInfo] entities.
 |===========================
 
 [[change-edit-input]]
@@ -3836,11 +4323,20 @@
 |`updated`            ||
 The link:rest-api.html#timestamp[timestamp] of when the change was last
 updated.
+|`submitted`          |only set for merged changes|
+The link:rest-api.html#timestamp[timestamp] of when the change was
+submitted.
 |`starred`            |not set if `false`|
-Whether the calling user has starred this change.
+Whether the calling user has starred this change with the default label.
+|`stars`              |optional|
+A list of star labels that are applied by the calling user to this
+change. The labels are lexicographically sorted.
 |`reviewed`           |not set if `false`|
 Whether the change was reviewed by the calling user.
 Only set if link:#reviewed[reviewed] is requested.
+|`submit_type`        |optional|
+The link:project-configuration.html#submit_type[submit type] of the change. +
+Not set for merged changes.
 |`mergeable`          |optional|
 Whether the change is mergeable. +
 Not set for merged changes, or if the change has not yet been tested.
@@ -3869,6 +4365,20 @@
 The reviewers that can be removed by the calling user as a list of
 link:rest-api-accounts.html#account-info[AccountInfo] entities. +
 Only set if link:#detailed-labels[detailed labels] are requested.
+|`reviewers`          ||
+The reviewers as a map that maps a reviewer state to a list of
+link:rest-api-accounts.html#account-info[AccountInfo] entities.
+Possible reviewer states are `REVIEWER`, `CC` and `REMOVED`. +
+`REVIEWER`: Users with at least one non-zero vote on the change. +
+`CC`: Users that were added to the change, but have not voted. +
+`REMOVED`: Users that were previously reviewers on the change, but have
+been removed. +
+Only set if link:#detailed-labels[detailed labels] are requested.
+|`reviewer_updates`|optional|
+Updates to reviewers set for the change as
+link:#review-update-info[ReviewerUpdateInfo] entities.
+Only set if link:#reviewer-updates[reviewer updates] are requested and
+if NoteDb is enabled.
 |`messages`|optional|
 Messages associated with the change as a list of
 link:#change-message-info[ChangeMessageInfo] entities. +
@@ -3889,9 +4399,31 @@
 |`problems`           |optional|
 A list of link:#problem-info[ProblemInfo] entities describing potential
 problems with this change. Only set if link:#check[CHECK] is set.
+|==================================
+
+[[change-input]]
+=== ChangeInput
+The `ChangeInput` entity contains information about creating a new change.
+
+[options="header",cols="1,^1,5"]
+|==================================
+|Field Name           ||Description
+|`project`            ||The name of the project.
+|`branch`             ||
+The name of the target branch. +
+The `refs/heads/` prefix is omitted.
+|`subject`            ||
+The subject of the change (header line of the commit message).
+|`topic`              |optional|The topic to which this change belongs.
+|`status`             |optional, default to `NEW`|
+The status of the change (only `NEW` and `DRAFT` accepted here).
 |`base_change`        |optional|
 A link:#change-id[\{change-id\}] that identifies the base change for a create
-change operation. Only used for the link:#create-change[CreateChange] endpoint.
+change operation.
+|`new_branch`         |optional, default to `false`|
+Allow creating a new branch when set to `true`.
+|`merge`              |optional|
+The detail of a merge commit as a link:#merge-input[MergeInput] entity.
 |==================================
 
 [[change-message-info]]
@@ -3910,6 +4442,11 @@
 |`date`            ||
 The link:rest-api.html#timestamp[timestamp] this message was posted.
 |`message`            ||The text left by the user.
+|`tag`                 |optional|
+Value of the `tag` field from link:#review-input[ReviewInput] set
+while posting the review.
+NOTE: To apply different tags on on different votes/comments multiple
+invocations of the REST call are required.
 |`_revision_number`    |optional|
 Which patchset (if any) generated this message.
 |==================================
@@ -3943,6 +4480,9 @@
 The side on which the comment was added. +
 Allowed values are `REVISION` and `PARENT`. +
 If not set, the default is `REVISION`.
+|`parent`      |optional|
+The 1-based parent number. Used only for merge commits when `side == PARENT`.
+When not set the comment is for the auto-merge tree.
 |`line`        |optional|
 The number of the line for which the comment was done. +
 If range is set, this equals the end line of the range. +
@@ -3960,6 +4500,11 @@
 The author of the message as an
 link:rest-api-accounts.html#account-info[AccountInfo] entity. +
 Unset for draft comments, assumed to be the calling user.
+|`tag`                 |optional|
+Value of the `tag` field from link:#review-input[ReviewInput] set
+while posting the review.
+NOTE: To apply different tags on on different votes/comments multiple
+invocations of the REST call are required.
 |===========================
 
 [[comment-input]]
@@ -3998,6 +4543,10 @@
 The comment message. +
 If not set and an existing draft comment is updated, the existing draft
 comment is deleted.
+|`tag`         |optional, drafts only|
+Value of the `tag` field. Only allowed on link:#create-draft[draft comment] +
+inputs; for published comments, use the `tag` field in +
+link#review-input[ReviewInput]
 |===========================
 
 [[comment-range]]
@@ -4040,6 +4589,24 @@
 link:#web-link-info[WebLinkInfo] entities.
 |===========================
 
+[[delete-vote-input]]
+=== DeleteVoteInput
+The `DeleteVoteInput` entity contains options for the deletion of a
+vote.
+
+[options="header",cols="1,^1,5"]
+|=======================
+|Field Name||Description
+|`label`   |optional|
+The label for which the vote should be deleted. +
+If set, must match the label in the URL.
+|`notify`  |optional|
+Notify handling that defines to whom email notifications should be sent
+after the vote is deleted. +
+Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
+If not set, the default is `ALL`.
+|=======================
+
 [[diff-content]]
 === DiffContent
 The `DiffContent` entity contains information about the content differences
@@ -4160,15 +4727,15 @@
 
 [options="header",cols="1,^1,5"]
 |===========================
-|Field Name    ||Description
-|`commit`      ||The commit of change edit as
+|Field Name     ||Description
+|`commit`       ||The commit of change edit as
 link:#commit-info[CommitInfo] entity.
-|`baseRevision`||The revision of the patch set change edit is based on.
-|`fetch`       ||
+|`base_revision`||The revision of the patch set the change edit is based on.
+|`fetch`        ||
 Information about how to fetch this patch set. The fetch information is
 provided as a map that maps the protocol name ("`git`", "`http`",
 "`ssh`") to link:#fetch-info[FetchInfo] entities.
-|`files`       |optional|
+|`files`        |optional|
 The files of the change edit as a map that maps the file names to
 link:#file-info[FileInfo] entities.
 |===========================
@@ -4212,6 +4779,8 @@
 Not set for binary files or if no lines were deleted.
 |`size_delta`    ||
 Number of bytes by which the file size increased/decreased.
+|`size`          ||
+File size in bytes.
 |=============================
 
 [[fix-input]]
@@ -4343,12 +4912,49 @@
 Submit type used for this change, can be `MERGE_IF_NECESSARY`,
 `FAST_FORWARD_ONLY`, `REBASE_IF_NECESSARY`, `MERGE_ALWAYS` or
 `CHERRY_PICK`.
+|`strategy`     |optional|
+The strategy of the merge, can be `recursive`, `resolve`,
+`simple-two-way-in-core`, `ours` or `theirs`.
 |`mergeable`     ||
 `true` if this change is cleanly mergeable, `false` otherwise
+|`commit_merged`     |optional|
+`true` if this change is already merged, `false` otherwise
+|`content_merged`     |optional|
+`true` if the content of this change is already merged, `false` otherwise
+|`conflicts`|optional|
+A list of paths with conflicts
 |`mergeable_into`|optional|
 A list of other branch names where this change could merge cleanly
 |============================
 
+[[merge-input]]
+=== MergeInput
+The `MergeInput` entity contains information about the merge
+
+[options="header",cols="1,^1,5"]
+|============================
+|Field Name      ||Description
+|`source`   ||
+The source to merge from, e.g. a complete or abbreviated commit SHA-1,
+a complete reference name, a short reference name under refs/heads, refs/tags,
+or refs/remotes namespace, etc.
+|`strategy`     |optional|
+The strategy of the merge, can be `recursive`, `resolve`,
+`simple-two-way-in-core`, `ours` or `theirs`, default will use project settings.
+|============================
+
+[[move-input]]
+=== MoveInput
+The `MoveInput` entity contains information for moving a change to a new branch.
+
+[options="header",cols="1,^1,5"]
+|===========================
+|Field Name          ||Description
+|`destination_branch`||Destination branch
+|`message`           |optional|
+A message to be posted in this change's comments
+|===========================
+
 [[problem-info]]
 === ProblemInfo
 The `ProblemInfo` entity contains a description of a potential consistency problem
@@ -4385,6 +4991,17 @@
 link:rest-api-accounts.html#gpg-key-info[GpgKeyInfo] entity.
 |===========================
 
+[[range-info]]
+=== RangeInfo
+The `RangeInfo` entity stores the coordinates of a range.
+
+[options="header",cols="1,6"]
+|===========================
+|Field Name   | Description
+|`start`      | First index.
+|`end`        | Last index.
+|===========================
+
 [[rebase-input]]
 === RebaseInput
 The `RebaseInput` entity contains information for changing parent when rebasing.
@@ -4469,6 +5086,26 @@
 voting values.
 |===========================
 
+[[review-update-info]]
+=== ReviewerUpdateInfo
+The `ReviewerUpdateInfo` entity contains information about updates to
+change's reviewers set.
+
+[options="header",cols="1,6"]
+|===========================
+|Field Name     |Description
+|`updated`|
+Timestamp of the update.
+|`updated_by`|
+The account which modified state of the reviewer in question as
+link:rest-api-accounts.html#account-info[AccountInfo] entity.
+|`reviewer`|
+The reviewer account added or removed from the change as an
+link:rest-api-accounts.html#account-info[AccountInfo] entity.
+|`state`|
+The reviewer state, one of `REVIEWER`, `CC` or `REMOVED`.
+|===========================
+
 [[review-input]]
 === ReviewInput
 The `ReviewInput` entity contains information for adding a review to a
@@ -4479,6 +5116,11 @@
 |Field Name               ||Description
 |`message`                |optional|
 The message to be added as review comment.
+|`tag`                    |optional|
+Apply this tag to the review comment message, votes, and inline
+comments. Tags may be used by CI or other automated systems to
+distinguish them from human reviews. Comments with specific tag
+values can be filtered out in the web UI.
 |`labels`                 |optional|
 The votes that should be added to the revision as a map that maps the
 label names to the voting values.
@@ -4545,11 +5187,19 @@
 ID] of one group for which all members should be added as reviewers. +
 If an ID identifies both an account and a group, only the account is
 added as reviewer to the change.
+|`state`       |optional|
+Add reviewer in this state. Possible reviewer states are `REVIEWER`
+and `CC`. If not given, defaults to `REVIEWER`.
 |`confirmed`   |optional|
 Whether adding the reviewer is confirmed. +
 The Gerrit server may be configured to
 link:config-gerrit.html#addreviewer.maxWithoutConfirmation[require a
 confirmation] when adding a group as reviewer that has many members.
+|`notify`  |optional|
+Notify handling that defines to whom email notifications should be sent
+after the reviewer is added. +
+Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
+If not set, the default is `ALL`.
 |===========================
 
 [[revision-info]]
@@ -4563,6 +5213,8 @@
 |===========================
 |Field Name    ||Description
 |`draft`       |not set if `false`|Whether the patch set is a draft.
+|`kind`        ||The change kind. Valid values are `REWORK`, `TRIVIAL_REBASE`,
+`MERGE_FIRST_PARENT_UPDATE`, `NO_CODE_CHANGE`, and `NO_CHANGE`.
 |`_number`     ||The patch set number.
 |`created`     ||
 The link:rest-api.html#timestamp[timestamp] of when the patch set was
@@ -4633,18 +5285,14 @@
 |Field Name    ||Description
 |`status`      ||
 The status of the change after submitting is `MERGED`.
-+
-As `wait_for_merge` in the link:#submit-input[SubmitInput] is deprecated and
-the request always waits for the merge to be completed, you can expect
-`MERGED` to be returned here.
 |`on_behalf_of`|optional|
 The link:rest-api-accounts.html#account-id[\{account-id\}] of the user on
 whose behalf the action should be done. To use this option the caller must
 have been granted both `Submit` and `Submit (On Behalf Of)` permissions.
 The user named by `on_behalf_of` does not need to be granted the `Submit`
 permission. This feature is aimed for CI solutions: the CI account can be
-granted both permssions, so individual users don't need `Submit` permission
-themselves. Still the changes can be submited on behalf of real users and
+granted both permissions, so individual users don't need `Submit` permission
+themselves. Still the changes can be submitted on behalf of real users and
 not with the identity of the CI account.
 |==========================
 
@@ -4655,8 +5303,17 @@
 [options="header",cols="1,^1,5"]
 |===========================
 |Field Name      ||Description
-|`wait_for_merge`|Deprecated, always `true`|
-Whether the request should wait for the merge to complete.
+|`on_behalf_of`|optional|
+If set, submit the change on behalf of the given user. The value may take any
+format link:rest-api-accounts.html#account-id[accepted by the accounts REST
+API]. Using this option requires
+link:access-control.html#category_submit_on_behalf_of[Submit (On Behalf Of)]
+permission on the branch.
+|`notify`|optional|
+Notify handling that defines to whom email notifications should be sent after
+the change is submitted. +
+Allowed values are `NONE`, `OWNER`, `OWNER_REVIEWERS` and `ALL`. +
+If not set, the default is `ALL`.
 |===========================
 
 [[submit-record]]
@@ -4694,6 +5351,23 @@
 the failure of the rule predicate.
 |===========================
 
+[[submitted-together-info]]
+=== SubmittedTogetherInfo
+The `SubmittedTogetherInfo` entity contains information about a
+collection of changes that would be submitted together.
+
+[options="header",cols="1,6"]
+|===========================
+|Field Name           |Description
+|`changes`            |
+A list of ChangeInfo entities representing the changes to be submitted together.
+|`non_visible_changes`|
+The number of changes to be submitted together that the current user
+cannot see. (This count includes changes that are visible to the
+current user when their reason for being submitted together involves
+changes the user cannot see.)
+|===========================
+
 [[suggested-reviewer-info]]
 === SuggestedReviewerInfo
 The `SuggestedReviewerInfo` entity contains information about a reviewer
@@ -4704,6 +5378,25 @@
 the `group` field that contains the
 link:rest-api-changes.html#group-base-info[GroupBaseInfo] entity.
 
+[options="header",cols="1,^1,5"]
+|===========================
+|Field Name    ||Description
+|`account`     |optional|
+An link:rest-api-accounts.html#account-info[AccountInfo] entity, if the
+suggestion is an account.
+|`group`       |optional|
+A link:rest-api-changes.html#group-base-info[GroupBaseInfo] entity, if the
+suggestion is a group.
+|`count`       ||
+The total number of accounts in the suggestion. This is `1` if `account` is
+present. If `group` is present, the total number of accounts that are
+members of the group is returned (this count includes members of nested
+groups).
+|`confirm`     |optional|
+True if `group` is present and `count` is above the threshold where the
+`confirmed` flag must be passed to add the group as a reviewer.
+|===========================
+
 [[topic-input]]
 === TopicInput
 The `TopicInput` entity contains information for setting a topic.
diff --git a/Documentation/rest-api-config.txt b/Documentation/rest-api-config.txt
index b1b795c..7b96a1c 100644
--- a/Documentation/rest-api-config.txt
+++ b/Documentation/rest-api-config.txt
@@ -115,6 +115,7 @@
     "gerrit": {
       "all_projects": "All-Projects",
       "all_users": "All-Users"
+      "doc_search": true
     },
     "sshd": {},
     "suggest": {
@@ -935,6 +936,258 @@
   ]
 ----
 
+[[get-user-preferences]]
+=== Get Default User Preferences
+--
+'GET /config/server/preferences'
+--
+
+Returns the default user preferences for the server.
+
+.Request
+----
+  GET /a/config/server/preferences HTTP/1.0
+----
+
+As response a link:rest-api-accounts.html#preferences-info[
+PreferencesInfo] is returned.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "changes_per_page": 25,
+    "show_site_header": true,
+    "use_flash_clipboard": true,
+    "download_command": "CHECKOUT",
+    "date_format": "STD",
+    "time_format": "HHMM_12",
+    "diff_view": "SIDE_BY_SIDE",
+    "size_bar_in_change_table": true,
+    "review_category_strategy": "NONE",
+    "mute_common_path_prefixes": true,
+    "my": [
+      {
+        "url": "#/dashboard/self",
+        "name": "Changes"
+      },
+      {
+        "url": "#/q/owner:self+is:draft",
+        "name": "Drafts"
+      },
+      {
+        "url": "#/q/has:draft",
+        "name": "Draft Comments"
+      },
+      {
+        "url": "#/q/has:edit",
+        "name": "Edits"
+      },
+      {
+        "url": "#/q/is:watched+is:open",
+        "name": "Watched Changes"
+      },
+      {
+        "url": "#/q/is:starred",
+        "name": "Starred Changes"
+      },
+      {
+        "url": "#/groups/self",
+        "name": "Groups"
+      }
+    ],
+    "email_strategy": "ENABLED"
+  }
+----
+
+[[set-user-preferences]]
+=== Set Default User Preferences
+
+--
+'PUT /config/server/preferences'
+--
+
+Sets the default user preferences for the server.
+
+The new user preferences must be provided in the request body as a
+link:rest-api-accounts.html#preferences-input[PreferencesInput]
+entity.
+
+To be allowed to set default preferences, a user must be a member of
+a group that is granted the
+link:access-control.html#capability_administrateServer[
+Administrate Server] capability.
+
+.Request
+----
+  PUT /a/config/server/preferences HTTP/1.0
+  Content-Type: application/json; charset=UTF-8
+
+  {
+    "changes_per_page": 50
+  }
+----
+
+As response a link:rest-api-accounts.html#preferences-info[
+PreferencesInfo] is returned.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "changes_per_page": 50,
+    "show_site_header": true,
+    "use_flash_clipboard": true,
+    "download_command": "CHECKOUT",
+    "date_format": "STD",
+    "time_format": "HHMM_12",
+    "diff_view": "SIDE_BY_SIDE",
+    "size_bar_in_change_table": true,
+    "review_category_strategy": "NONE",
+    "mute_common_path_prefixes": true,
+    "my": [
+      {
+        "url": "#/dashboard/self",
+        "name": "Changes"
+      },
+      {
+        "url": "#/q/owner:self+is:draft",
+        "name": "Drafts"
+      },
+      {
+        "url": "#/q/has:draft",
+        "name": "Draft Comments"
+      },
+      {
+        "url": "#/q/has:edit",
+        "name": "Edits"
+      },
+      {
+        "url": "#/q/is:watched+is:open",
+        "name": "Watched Changes"
+      },
+      {
+        "url": "#/q/is:starred",
+        "name": "Starred Changes"
+      },
+      {
+        "url": "#/groups/self",
+        "name": "Groups"
+      }
+    ],
+    "email_strategy": "ENABLED"
+  }
+----
+
+[[get-diff-preferences]]
+=== Get Default Diff Preferences
+
+--
+'GET /config/server/preferences.diff'
+--
+
+Returns the default diff preferences for the server.
+
+.Request
+----
+  GET /a/config/server/preferences.diff HTTP/1.0
+----
+
+As response a link:rest-api-accounts.html#diff-preferences-info[
+DiffPreferencesInfo] is returned.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "context": 10,
+    "tab_size": 8,
+    "line_length": 100,
+    "cursor_blink_rate": 0,
+    "intraline_difference": true,
+    "show_line_endings": true,
+    "show_tabs": true,
+    "show_whitespace_errors": true,
+    "syntax_highlighting": true,
+    "auto_hide_diff_table_header": true,
+    "theme": "DEFAULT",
+    "ignore_whitespace": "IGNORE_NONE"
+  }
+----
+
+[[set-diff-preferences]]
+=== Set Default Diff Preferences
+
+--
+'PUT /config/server/preferences.diff'
+--
+
+Sets the default diff preferences for the server.
+
+The new diff preferences must be provided in the request body as a
+link:rest-api-accounts.html#diff-preferences-input[
+DiffPreferencesInput] entity.
+
+To be allowed to set default diff preferences, a user must be a member
+of a group that is granted the
+link:access-control.html#capability_administrateServer[
+Administrate Server] capability.
+
+.Request
+----
+  PUT /a/config/server/preferences.diff HTTP/1.0
+  Content-Type: application/json; charset=UTF-8
+
+  {
+    "context": 10,
+    "tab_size": 8,
+    "line_length": 80,
+    "cursor_blink_rate": 0,
+    "intraline_difference": true,
+    "show_line_endings": true,
+    "show_tabs": true,
+    "show_whitespace_errors": true,
+    "syntax_highlighting": true,
+    "auto_hide_diff_table_header": true,
+    "theme": "DEFAULT",
+    "ignore_whitespace": "IGNORE_NONE"
+  }
+----
+
+As response a link:rest-api-accounts.html#diff-preferences-info[
+DiffPreferencesInfo] is returned.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "context": 10,
+    "tab_size": 8,
+    "line_length": 80,
+    "cursor_blink_rate": 0,
+    "intraline_difference": true,
+    "show_line_endings": true,
+    "show_tabs": true,
+    "show_whitespace_errors": true,
+    "syntax_highlighting": true,
+    "auto_hide_diff_table_header": true,
+    "theme": "DEFAULT",
+    "ignore_whitespace": "IGNORE_NONE"
+  }
+----
+
 
 [[ids]]
 == IDs
@@ -1008,6 +1261,12 @@
 is used for Git over HTTP/HTTPS]. Only set if
 link:config-gerrit.html#auth.type[authentication type] is is `LDAP` or
 `LDAP_BIND`.
+|`git_basic_auth_policy`      |optional|
+The link:config-gerrit.html#auth.gitBasicAuthPolicy[policy] to authenticate
+Git over HTTP and REST API requests when
+link:config-gerrit.html#auth.type[authentication type] is `LDAP` and
+link:config-gerrit.html#auth.gitBasicAuth[basic authentication] is set to true.
+Can be `HTTP`, `LDAP` or `HTTP_LDAP`.
 |==========================================
 
 [[cache-info]]
@@ -1075,6 +1334,9 @@
 [options="header",cols="1,^1,5"]
 |=============================
 |Field Name           ||Description
+|`allow_blame`        |not set if `false`|
+link:config-gerrit.html#change.allowBlame[Whether blame on side by side diff is
+allowed].
 |`allow_drafts`       |not set if `false`|
 link:config-gerrit.html#change.allowDrafts[Whether draft workflow is
 allowed].
@@ -1189,6 +1451,8 @@
 |`all_users_name`    ||
 Name of the link:config-gerrit.html#gerrit.allUsers[project in which
 meta data of all users is stored].
+|`doc_search`        ||
+Whether documentation search is available.
 |`doc_url`           |optional|
 Custom base URL where Gerrit server documentation is located.
 (Documentation may still be available at /Documentation relative to the
@@ -1202,54 +1466,6 @@
 bugs link].
 |=================================
 
-[[git-web-info]]
-=== GitwebInfo
-The `GitwebInfo` entity contains information about the
-link:config-gerrit.html#gitweb[gitweb] configuration.
-
-[options="header",cols="1,6"]
-|=======================
-|Field Name |Description
-|`url`      |
-The link:config-gerrit.html#gitweb.url[gitweb base URL].
-|`type`     |
-The link:config-gerrit.html#gitweb.type[gitweb type] as
-link:#git-web-type-info[GitwebTypeInfo] entity.
-|=======================
-
-[[git-web-type-info]]
-=== GitwebTypeInfo
-The `GitwebTypeInfo` entity contains information about the
-link:config-gerrit.html#gitweb[gitweb] configuration.
-
-[options="header",cols="1,^1,5"]
-|=============================
-|Field Name      ||Description
-|`name`          ||
-The link:config-gerrit.html#gitweb.linkname[gitweb link name].
-|`revision`      |optional|
-The link:config-gerrit.html#gitweb.revision[gitweb revision pattern].
-|`project`       |optional|
-The link:config-gerrit.html#gitweb.project[gitweb project pattern].
-|`branch`        |optional|
-The link:config-gerrit.html#gitweb.branch[gitweb branch pattern].
-|`root_tree`     |optional|
-The link:config-gerrit.html#gitweb.roottree[gitweb root tree pattern].
-|`file`          |optional|
-The link:config-gerrit.html#gitweb.file[gitweb file pattern].
-|`file_history`  |optional|
-The link:config-gerrit.html#gitweb.filehistory[gitweb file history
-pattern].
-|`path_separator`||
-The link:config-gerrit.html#gitweb.pathSeparator[gitweb path separator].
-|`link_drafts`   |optional|
-link:config-gerrit.html#gitweb.linkDrafts[Whether Gerrit should provide
-links to gitweb on draft patch set.]
-|`url_encode`    |optional|
-link:config-gerrit.html#gitweb.urlEncode[Whether Gerrit should encode
-the generated viewer URL.]
-|=============================
-
 [[hit-ration-info]]
 === HitRatioInfo
 The `HitRatioInfo` entity contains information about the hit ratio of a
@@ -1361,8 +1577,8 @@
 Information about the configuration from the
 link:config-gerrit.html#gerrit[gerrit] section as link:#gerrit-info[
 GerritInfo] entity.
-|`gitweb `                 |optional|
-Information about the link:config-gerrit.html#gitweb[gitweb]
+|`note_db_enabled`         |not set if `false`|
+Whether the NoteDb storage backend is fully enabled.
 |`plugin `                 ||
 Information about Gerrit extensions by plugins as
 link:#plugin-config-info[PluginConfigInfo] entity.
diff --git a/Documentation/rest-api-groups.txt b/Documentation/rest-api-groups.txt
index e0df4ca..23d4c5b 100644
--- a/Documentation/rest-api-groups.txt
+++ b/Documentation/rest-api-groups.txt
@@ -174,13 +174,12 @@
 
 [[suggest-group]]
 ==== Suggest Group
-The `suggest` option indicates a user-entered string that
+The `suggest` or `s` option indicates a user-entered string that
 should be auto-completed to group names.
 If this option is set and `n` is not set, then `n` defaults to 10.
 
-When using this option,
-the `project` or `p` option can be used to name the current project,
-to allow context-dependent suggestions.
+When using this option, the `project` or `p` option can be used to
+name the current project, to allow context-dependent suggestions.
 
 Not compatible with `visible-to-all`, `owned`, `user`, `match`, `q`,
 or `S`.
@@ -1315,10 +1314,12 @@
 |`visible_to_all`|optional|
 Whether the group is visible to all registered users. +
 `false` if not set.
-|`owner_id`|optional|The URL encoded ID of the owner group. +
+|`owner_id`      |optional|The URL encoded ID of the owner group. +
 This can be a group UUID, a legacy numeric group ID or a unique group
 name. +
 If not set, the new group will be self-owned.
+|`members`       |optional|The initial members in a list of +
+link:#account-id[account ids].
 |===========================
 
 [[group-options-info]]
diff --git a/Documentation/rest-api-projects.txt b/Documentation/rest-api-projects.txt
index 986ccd8..457a287 100644
--- a/Documentation/rest-api-projects.txt
+++ b/Documentation/rest-api-projects.txt
@@ -733,6 +733,7 @@
     "create_new_change_for_all_not_in_target": "INHERIT",
     "enable_signed_push": "INHERIT",
     "require_signed_push": "INHERIT",
+    "reject_implicit_merges": "INHERIT",
     "require_change_id": "TRUE",
     "max_object_size_limit": "10m",
     "submit_type": "REBASE_IF_NECESSARY",
@@ -786,6 +787,11 @@
       "configured_value": "INHERIT",
       "inherited_value": false
     },
+    "reject_implicit_merges": {
+      "value": false,
+      "configured_value": "INHERIT",
+      "inherited_value": false
+    },
     "max_object_size_limit": {
       "value": "10m",
       "configured_value": "10m",
@@ -844,6 +850,34 @@
   done.
 ----
 
+==== Asynchronous Execution
+
+The option `async` allows to schedule a background task that asynchronously
+executes a Git garbage collection.
+
+The `Location` header of the response refers to the link:rest-api-config.html#get-task[background task]
+which allows to inspect the progress of its execution. In case of asynchronous
+execution the `show_progress` option is ignored.
+
+.Request
+----
+  POST /projects/plugins%2Freplication/gc HTTP/1.0
+  Content-Type: application/json;charset=UTF-8
+
+  {
+    "async": true
+  }
+----
+
+The response is empty.
+
+.Response
+----
+  HTTP/1.1 202 Accepted
+  Content-Disposition: attachment
+  Location: https:<host>/a/config/server/tasks/383a0602
+----
+
 [[ban-commit]]
 === Ban Commit
 --
@@ -895,6 +929,143 @@
   }
 ----
 
+[[get-access]]
+=== List Access Rights for Project
+--
+'GET /projects/link:rest-api-projects.html#project-name[\{project-name\}]/access'
+--
+
+Lists the access rights for a single project.
+
+As result a link:#project-access-info[ProjectAccessInfo] entity is returned.
+
+.Request
+----
+  GET /projects/MyProject/access HTTP/1.0
+----
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "revision": "61157ed63e14d261b6dca40650472a9b0bd88474",
+    "inherits_from": {
+      "id": "All-Projects",
+      "name": "All-Projects",
+      "description": "Access inherited by all other projects."
+    },
+    "local": {
+        "refs/*": {
+          "permissions": {
+            "read": {
+              "rules": {
+                "c2ce4749a32ceb82cd6adcce65b8216e12afb41c": {
+                  "action": "ALLOW",
+                  "force": false
+                },
+                "global:Anonymous-Users": {
+                  "action": "ALLOW",
+                  "force": false
+                }
+              }
+            }
+          }
+        }
+    },
+    "is_owner": true,
+    "owner_of": [
+      "refs/*"
+    ],
+    "can_upload": true,
+    "can_add": true,
+    "config_visible": true
+  }
+----
+
+[[set-access]]
+=== Add, Update and Delete Access Rights for Project
+--
+'POST /projects/link:rest-api-projects.html#project-name[\{project-name\}]/access'
+--
+
+Sets access rights for the project using the diff schema provided by
+link:#project-access-input[ProjectAccessInput]. Deductions are used to
+remove access sections, permissions or permission rules. The backend will remove
+the entity with the finest granularity in the request, meaning that if an
+access section without permissions is posted, the access section will be
+removed; if an access section with a permission but no permission rules is
+posted, the permission will be removed; if an access section with a permission
+and a permission rule is posted, the permission rule will be removed.
+
+Additionally, access sections and permissions will be cleaned up after applying
+the deductions by removing items that have no child elements.
+
+After removals have been applied, additions will be applied.
+
+As result a link:#project-access-info[ProjectAccessInfo] entity is returned.
+
+.Request
+----
+  POST /projects/MyProject/access HTTP/1.0
+  Content-Type: application/json; charset=UTF-8
+
+  {
+    "remove": [
+      "refs/*": {
+        "permissions": {
+          "read": {
+            "rules": {
+              "c2ce4749a32ceb82cd6adcce65b8216e12afb41c": {
+                "action": "ALLOW"
+              }
+            }
+          }
+        }
+      }
+    ]
+  }
+----
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "revision": "61157ed63e14d261b6dca40650472a9b0bd88474",
+    "inherits_from": {
+      "id": "All-Projects",
+      "name": "All-Projects",
+      "description": "Access inherited by all other projects."
+    },
+    "local": {
+        "refs/*": {
+          "permissions": {
+            "read": {
+              "rules": {
+                "global:Anonymous-Users": {
+                  "action": "ALLOW",
+                  "force": false
+                }
+              }
+            }
+          }
+        }
+    },
+    "is_owner": true,
+    "owner_of": [
+      "refs/*"
+    ],
+    "can_upload": true,
+    "can_add": true,
+    "config_visible": true
+  }
+----
+
 [[branch-endpoints]]
 == Branch Endpoints
 
@@ -1189,6 +1360,101 @@
   Ly8gQ29weXJpZ2h0IChDKSAyMDEwIFRoZSBBbmRyb2lkIE9wZW4gU291cmNlIFByb2plY...
 ----
 
+
+[[get-mergeable-info]]
+=== Get Mergeable Information
+--
+'GET /projects/link:#project-name[\{project-name\}]/branches/link:#branch-id[\{branch-id\}]/mergeable'
+--
+
+Gets whether the source is mergeable with the target branch.
+
+The `source` query parameter is required, which can be anything that could be
+resolved to a commit, see examples of the `source` attribute in
+link:rest-api-changes.html#merge-input[MergeInput].
+
+Also takes an optional parameter `strategy`, which can be `recursive`, `resolve`,
+`simple-two-way-in-core`, `ours` or `theirs`, default will use project settings.
+
+.Request
+----
+  GET /projects/test/branches/master/mergeable?source=testbranch&strategy=recursive HTTP/1.0
+----
+
+As response a link:rest-api-changes.html#mergeable-info[MergeableInfo] entity is returned.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "submit_type": "MERGE_IF_NECESSARY",
+    "strategy": "recursive",
+    "mergeable": true,
+    "commit_merged": false,
+    "content_merged": false
+  }
+----
+
+or when there were conflicts.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "submit_type": "MERGE_IF_NECESSARY",
+    "strategy": "recursive",
+    "mergeable": false,
+    "conflicts": [
+      "common.txt",
+      "shared.txt"
+    ]
+  }
+----
+
+or when the 'testbranch' has been already merged.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "submit_type": "MERGE_IF_NECESSARY",
+    "strategy": "recursive",
+    "mergeable": true,
+    "commit_merged": true,
+    "content_merged": true
+  }
+----
+
+or when only the content of 'testbranch' has been merged.
+
+.Response
+----
+  HTTP/1.1 200 OK
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+  {
+    "submit_type": "MERGE_IF_NECESSARY",
+    "strategy": "recursive",
+    "mergeable": true,
+    "commit_merged": false,
+    "content_merged": true
+  }
+----
+
 [[get-reflog]]
 === Get Reflog
 --
@@ -1403,6 +1669,57 @@
 [[tag-endpoints]]
 == Tag Endpoints
 
+[[create-tag]]
+=== Create Tag
+
+--
+'PUT /projects/link:#project-name[\{project-name\}]/tags/link:#tag-id[\{tag-id\}]'
+--
+
+Create a new tag on the project.
+
+In the request body additional data for the tag can be provided as
+link:#tag-input[TagInput].
+
+If a message is provided in the input, the tag is created as an
+annotated tag with the current user as tagger. Signed tags are not
+supported.
+
+.Request
+----
+  PUT /projects/MyProject/tags/v1.0 HTTP/1.0
+  Content-Type: application/json; charset=UTF-8
+
+  {
+    "message": "annotation",
+    "revision": "c83117624b5b5d8a7f86093824e2f9c1ed309d63"
+  }
+----
+
+As response a link:#tag-info[TagInfo] entity is returned that describes
+the created tag.
+
+.Response
+----
+  HTTP/1.1 201 Created
+  Content-Disposition: attachment
+  Content-Type: application/json; charset=UTF-8
+
+  )]}'
+
+  "object": "d48d304adc4b6674e11dc2c018ea05fcbdda32fd",
+  "message": "annotation",
+  "tagger": {
+    "name": "David Pursehouse",
+    "email": "dpursehouse@collab.net",
+    "date": "2016-06-06 01:22:03.000000000",
+    "tz": 540
+  },
+  "ref": "refs/tags/v1.0",
+  "revision": "c83117624b5b5d8a7f86093824e2f9c1ed309d63"
+  }
+----
+
 [[list-tags]]
 === List Tags
 --
@@ -1988,14 +2305,15 @@
 valid link:user-changeid.html[Change-Id] footer in any commit uploaded
 for review is required. This does not apply to commits pushed directly
 to a branch or tag.
-|`enable_signed_push`|
-optional, not set if signed push is disabled|
+|`enable_signed_push`|optional, not set if signed push is disabled|
 link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether
 signed push validation is enabled on the project.
-|`require_signed_push`|
-optional, not set if signed push is disabled
+|`require_signed_push`|optional, not set if signed push is disabled|
 link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether
 signed push validation is required on the project.
+|`reject_implicit_merges`|optional|
+link:#inherited-boolean-info[InheritedBooleanInfo] that tells whether
+implicit merges should be rejected on changes pushed to the project.
 |`max_object_size_limit`     ||
 The link:config-gerrit.html#receive.maxObjectSizeLimit[max object size
 limit] of this project as a link:#max-object-size-limit-info[
@@ -2064,6 +2382,11 @@
 directly to a branch or tag. +
 Can be `TRUE`, `FALSE` or `INHERIT`. +
 If not set, this setting is not updated.
+|`reject_implicit_merges`                  |optional|
+Whether a check for implicit merges will be performed when changes
+are pushed for review. +
+Can be `TRUE`, `FALSE` or `INHERIT`. +
+If not set, this setting is not updated.
 |`max_object_size_limit`                   |optional|
 The link:config-gerrit.html#receive.maxObjectSizeLimit[max object size
 limit] of this project as a link:#max-object-size-limit-info[
@@ -2108,7 +2431,7 @@
 `configured_value` and `inherited_value`.
 |`values`          |optional|
 The list of values. Only set if the `type` is `ARRAY`.
-`editable`         |`false` if not set|
+|`editable`         |`false` if not set|
 Whether the value is editable.
 |`permitted_values`|optional|
 The list of permitted values. Only set if the `type` is `LIST`.
@@ -2212,6 +2535,8 @@
 Whether progress information should be shown.
 |`aggressive`    |`false` if not set|
 Whether an aggressive garbage collection should be done.
+|`async`         |`false` if not set|
+Whether the garbage collection should run asynchronously.
 |=============================
 
 [[head-input]]
@@ -2265,6 +2590,27 @@
 Not set if there is no global limit for the object size.
 |===============================
 
+[[project-access-input]]
+=== ProjectAccessInput
+The `ProjectAccessInput` describes changes that should be applied to a project
+access config.
+
+[options="header",cols="1,^2,4"]
+|=============================
+|Field Name          |        |Description
+|`remove`            |optional|
+A list of deductions to be applied to the project access as
+link:rest-api-access.html#project-access-info[ProjectAccessInfo] entities.
+|`add`               |optional|
+A list of additions to be applied to the project access as
+link:rest-api-access.html#project-access-info[ProjectAccessInfo] entities.
+|`message`           |optional|
+A commit message for this change.
+|`parent`            |optional|
+A new parent for the project to inherit from. Changing the parent project
+requires administrative privileges.
+|=============================
+
 [[project-description-input]]
 === ProjectDescriptionInput
 The `ProjectDescriptionInput` entity contains information for setting a
@@ -2429,6 +2775,22 @@
 link:rest-api-changes.html#git-person-info[GitPersonInfo] entity.
 |=========================
 
+[[tag-input]]
+=== TagInput
+
+The `TagInput` entity contains information for creating a tag.
+
+[options="header",cols="1,^2,4"]
+|=========================
+|Field Name  ||Description
+|`ref`       ||The name of the tag. The leading `refs/tags/` is optional.
+|`revision`  |optional|The revision to which the tag should point. If not
+specified, the project's `HEAD` will be used.
+|`message`   |optional|The tag message. When set, the tag will be created
+as an annotated tag.
+|=========================
+
+
 [[theme-info]]
 === ThemeInfo
 The `ThemeInfo` entity describes a theme.
@@ -2444,6 +2806,7 @@
 The path to the `GerritSiteFooter.html` file.
 |=============================
 
+----
 
 GERRIT
 ------
diff --git a/Documentation/rest-api.txt b/Documentation/rest-api.txt
index a87f5b6..7f7e62e 100644
--- a/Documentation/rest-api.txt
+++ b/Documentation/rest-api.txt
@@ -97,6 +97,9 @@
 in the link:http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html[
 HTTP specification].
 
+In most cases, the response body of an error response will be a
+plaintext, human-readable error message.
+
 Here are examples that show how HTTP status codes are used in the
 context of the Gerrit REST API.
 
diff --git a/Documentation/user-inline-edit.txt b/Documentation/user-inline-edit.txt
index 05932df..f3c8b00 100644
--- a/Documentation/user-inline-edit.txt
+++ b/Documentation/user-inline-edit.txt
@@ -173,7 +173,7 @@
 change it, save it, close edit screen and select next file from the file table to edit.
 "<-" | "->" icons in header of edit screen could be used to navigate to the next file to
 change from the file table. This would behave like the navigation icons in side by side
-with thefollowing logic on click:
+with the following logic on click:
 
 ** "save-when-file-was-changed" or
 ** "close-when-no-changes"
diff --git a/Documentation/user-notify.txt b/Documentation/user-notify.txt
index 9dffa51..4dc4880 100644
--- a/Documentation/user-notify.txt
+++ b/Documentation/user-notify.txt
@@ -45,24 +45,24 @@
 details on how access permissions work.
 
 Initialize a temporary Git repository to edit the configuration:
-====
+----
   mkdir cfg_dir
   cd cfg_dir
   git init
-====
+----
 
 Download the existing configuration from Gerrit:
-====
+----
   git fetch ssh://localhost:29418/project refs/meta/config
   git checkout FETCH_HEAD
-====
+----
 
 Enable notifications to an email address by adding to
 `project.config`, this can be done using the `git config` command:
-====
+----
   git config -f project.config --add notify.team.email team-address@example.com
   git config -f project.config --add notify.team.email paranoid-manager@example.com
-====
+----
 
 Examining the project.config file with any text editor should show
 a new notify section describing the email addresses to deliver to:
@@ -79,10 +79,10 @@
 if different filters are needed.
 
 Commit the configuration change, and push it back:
-====
+----
   git commit -a -m "Notify team-address@example.com of changes"
   git push ssh://localhost:29418/project HEAD:refs/meta/config
-====
+----
 
 [[notify.name.email]]notify.<name>.email::
 +
@@ -132,11 +132,11 @@
 security filtering by adding the `visibleto:groupname` predicate to
 the filter expression, for example:
 
-====
+----
   [notify "Developers"]
   	email = team-address@example.com
   	filter = visibleto:Developers
-====
+----
 
 When sending email to an internal group, the internal group's read
 access is automatically checked by Gerrit and therefore does not
diff --git a/Documentation/user-review-ui.txt b/Documentation/user-review-ui.txt
index 859765c..838a433 100644
--- a/Documentation/user-review-ui.txt
+++ b/Documentation/user-review-ui.txt
@@ -187,6 +187,19 @@
 the link:access-control.html#category_submit[Submit] access right is
 assigned.
 
+** [[revert]]`Revert`:
++
+Reverts the change via creating a new one.
++
+The `Revert` button is available if the change has been submitted.
++
+When the `Revert` button is pressed, a panel will appear to allow
+the user to enter a commit message for the reverting change.
++
+Once a revert change is created, the original author and any reviewers
+of the original change are added as reviewers and a message is posted
+to the original change linking to the revert.
+
 ** [[abandon]]`Abandon`:
 +
 Abandons the change.
@@ -387,6 +400,10 @@
 
 image::images/user-review-ui-change-screen-patch-sets.png[width=800, link="images/user-review-ui-change-screen-patch-sets.png"]
 
+Another indication is a highlighted drop-down label.
+
+image::images/user-review-ui-change-screen-not-current.png[width=800, link="images/user-review-ui-change-screen-not-current.png"]
+
 [[patch-set-drop-down]]
 The patch set drop-down list shows the list of patch sets and allows to
 switch between them. The patch sets are sorted in descending order so
@@ -591,8 +608,12 @@
 
 Clicking on the `Reply...` button opens a popup panel.
 
+[[summary-comment]]
 A text box allows to type a summary comment for the currently viewed
-patch set.
+patch set. Some basic markdown-like syntax is supported which renders
+indented lines preformatted, lines starting with "- " or "* " as list
+items, and lines starting with "> " as block quotes (also see replying to
+link:#reply-to-message[messages] and link:#reply-inline-comment[inline comments]).
 
 Note that you can set the text and tooltip of the button in
 link:config-gerrit.html#change.replyLabel[gerrit.config].
@@ -649,7 +670,7 @@
 reply icon in the right upper corner of a change message. This opens
 the reply popup panel and prefills the text box with the quoted comment.
 Then the reply can be written below the quoted comment or inserted
-inline. Lines starting with " > " will be rendered as a block quote.
+inline. Lines starting with "> " will be rendered as a block quote.
 Please note that for a correct rendering it is important to leave a blank
 line between a quoted block and the reply to it.
 
@@ -818,7 +839,7 @@
 Clicking on the `Reply` button opens an editor to type the reply.
 
 Quoting is supported, but only by manually copying & pasting the old
-comment that should be quoted and prefixing every line by " > ". Please
+comment that should be quoted and prefixing every line by "> ". Please
 note that for a correct rendering it is important to leave a blank line
 between a quoted block and the reply to it.
 
diff --git a/Documentation/user-search-accounts.txt b/Documentation/user-search-accounts.txt
new file mode 100644
index 0000000..15d87b0
--- /dev/null
+++ b/Documentation/user-search-accounts.txt
@@ -0,0 +1,83 @@
+= Gerrit Code Review - Searching Accounts
+
+== Basic Change Search
+
+Similar to many popular search engines on the web, just enter some
+text and let Gerrit figure out the meaning:
+
+[options="header"]
+|=============================================================
+|Description                      | Examples
+|Name                             | John
+|Email address                    | jdoe@example.com
+|Username                         | jdoe
+|Account-Id                       | 1000096
+|Own account                      | self
+|=============================================================
+
+[[search-operators]]
+== Search Operators
+
+Operators act as restrictions on the search. As more operators
+are added to the same query string, they further restrict the
+returned results. Search can also be performed by typing only a
+text with no operator, which will match against a variety of fields.
+
+[[email]]
+email:'EMAIL'::
++
+Matches accounts that have the email address 'EMAIL' or an email
+address that starts with 'EMAIL'.
+
+[[is]]
+[[is-active]]
+is:active::
++
+Matches accounts that are active.
+
+[[is-inactive]]
+is:inactive::
++
+Matches accounts that are inactive.
+
+[[name]]
+name:'NAME'::
++
+Matches accounts that have any name part 'NAME'. The name parts consist
+of any part of the full name and the email addresses.
+
+[[username]]
+username:'USERNAME'::
++
+Matches accounts that have the username 'USERNAME'.
+
+== Magical Operators
+
+[[is-visible]]
+is:visible::
++
+Magical internal flag to prove the current user has access to read
+the change. This flag is always added to any query.
+
+[[is-active-magic]]
+is:active::
++
+Matches accounts that are active. If neither link:#is-active[is:active]
+nor link:#is-inactive[is:inactive] is contained in a query, `is:active`
+is automatically added so that by default only active accounts are
+matched.
+
+[[limit]]
+limit:'CNT'::
++
+Limit the returned results to no more than 'CNT' records. This is
+automatically set to the page size configured in the current user's
+preferences. Including it in a web query may lead to unpredictable
+results with regards to pagination.
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------
diff --git a/Documentation/user-search.txt b/Documentation/user-search.txt
index b2b3614..b04898e 100644
--- a/Documentation/user-search.txt
+++ b/Documentation/user-search.txt
@@ -247,25 +247,43 @@
 Regular expression matching can be enabled by starting the string
 with `^`. In this mode `file:` is an alias of `path:` (see above).
 
+[[star]]
+star:'LABEL'::
++
+Matches any change that was starred by the current user with the label
+'LABEL'.
++
+E.g. if changes that are not interesting are marked with an `ignore`
+star, they could be filtered out by '-star:ignore'.
++
+'star:star' is the same as 'has:star' and 'is:starred'.
+
 [[has]]
 has:draft::
 +
 True if there is a draft comment saved by the current user.
 
+[[has-star]]
 has:star::
 +
-Same as 'is:starred', true if the change has been starred by the
-current user.
+Same as 'is:starred' and 'star:star', true if the change has been
+starred by the current user with the default label.
+
+[[has-stars]]
+has:stars::
++
+True if the change has been starred by the current user with any label.
 
 has:edit::
 +
 True if the change has inline edit created by the current user.
 
 [[is]]
+[[is-starred]]
 is:starred::
 +
 Same as 'has:star', true if the change has been starred by the
-current user.
+current user with the default label.
 
 is:watched::
 +
@@ -510,7 +528,7 @@
 
 starredby:'USER'::
 +
-Matches changes that have been starred by 'USER'.
+Matches changes that have been starred by 'USER' with the default label.
 The special case `starredby:self` applies to the caller.
 
 watchedby:'USER'::
diff --git a/Documentation/user-submodules.txt b/Documentation/user-submodules.txt
index 151ac71..2754b45 100644
--- a/Documentation/user-submodules.txt
+++ b/Documentation/user-submodules.txt
@@ -1,78 +1,127 @@
 = Gerrit Code Review - Superproject subscription to submodules updates
 
+[[automatic_update]]
 == Description
-
 Gerrit supports a custom git superproject feature for tracking submodules.
 This feature is useful for automatic updates on superprojects whenever
-a change is merged on tracked submodules. To take advantage of this
-feature, one should add submodule(s) to a local working copy of a
-superproject, edit the created .gitmodules configuration file to
-have a branch field on each submodule section with the value of the
-submodule branch it is subscribing to, commit the changes, push and
-merge the commit.
+a change is merged on tracked submodules.
 
-When a commit is merged to a project, the commit content is scanned
-to identify if it registers git submodules (if the commit registers
-any gitlinks and .gitmodules file with required info) and if so,
-a new submodule subscription is registered.
+When a superproject is subscribed to a submodule, it is not
+required to push/merge commits to this superproject to update the
+gitlink to the submodule. Whenever a commit is merged in a submodule,
+its subscribed superproject is updated by Gerrit.
 
-When a new commit of a registered submodule is merged, Gerrit
-automatically updates the subscribers to the submodule with a new
-commit having the updated gitlinks.
+Imagine a superproject called 'super' having a branch called 'dev'
+having subscribed to a submodule 'sub' on a branch 'dev-of-sub'. When a commit
+is merged in branch 'dev-of-sub' of 'sub' project, Gerrit automatically
+creates a new commit on branch 'dev' of 'super' updating the gitlink
+to point to the just merged commit.
 
-== Git Submodules Overview
+To take advantage of this feature, one should:
 
-Submodules are a git feature that allows an external repository to be
+. ensure superproject subscriptions are enabled on the server via
+  link:config-gerrit.html#submodule.enableSuperProjectSubscriptions[submodule.enableSuperProjectSubscriptions]
+. configure the submodule to allow having a superproject subscribed
+. ensure the .gitmodules file of the superproject includes
+.. a branch field
+.. a url that starts with the link:config-gerrit.html#gerrit.canonicalWebUrl[`gerrit.canonicalWebUrl`]
+
+When a commit in a project is merged, Gerrit checks for superprojects
+that are subscribed to the the project and automatically updates those
+superprojects with a commit that updates the gilink for the project.
+
+This feature is enabled by default and can be disabled
+via link:config-gerrit.html#submodule.enableSuperProjectSubscriptions[submodule.enableSuperProjectSubscriptions]
+in the server configuration.
+
+== Git submodules overview
+
+Submodules are a Git feature that allows an external repository to be
 attached inside a repository at a specific path. The objective here
 is to provide a brief overview, further details can be found
-in the official git submodule command documentation.
+in the official Git submodule documentation.
 
-Imagine a repository called 'super' and another one called 'a'.
-Also consider 'a' available in a running Gerrit instance on "server".
-With this feature, one could attach 'a' inside of 'super' repository
-at path 'a' by executing the following command when being inside
+Imagine a repository called 'super' and another one called 'sub'.
+Also consider 'sub' available in a running Gerrit instance on "server".
+With this feature, one could attach 'sub' inside of 'super' repository
+at path 'sub' by executing the following command when being inside
 'super':
-=====
-git submodule add ssh://server/a a
-=====
+----
+git submodule add ssh://server/sub sub
+----
 
 Still considering the above example, after its execution notice that
-inside the local repository 'super' the 'a' folder is considered a
-gitlink to the external repository 'a'. Also notice a file called
+inside the local repository 'super' the 'sub' folder is considered a
+gitlink to the external repository 'sub'. Also notice a file called
 .gitmodules is created (it is a configuration file containing the
-subscription of 'a'). To provide the SHA-1 each gitlink points to in
+subscription of 'sub'). To provide the SHA-1 each gitlink points to in
 the external repository, one should use the command:
-====
+----
 git submodule status
-====
+----
 
-In the example provided, if 'a' is updated and 'super' is supposed
-to see the latest SHA-1 (considering here 'a' has only the master
-branch), one should then commit the modified gitlink for 'a' in
+In the example provided, if 'sub' is updated and 'super' is supposed
+to see the latest SHA-1 (considering here 'sub' has only the master
+branch), one should then commit the modified gitlink for 'sub' in
 the 'super' project. Actually it would not even need to be an
-external update, one could move to 'a' folder (insider 'super'),
+external update, one could move to 'sub' folder (inside 'super'),
 modify its content, commit, then move back to 'super' and
-commit the modified gitlink for 'a'.
+commit the modified gitlink for 'sub'.
 
-== Creating a New Subscription
+== Creating a new subscription
 
-=== Defining the Submodule Branch
+=== Ensure the subscription is allowed
 
-This is required because submodule subscription is actually the
-subscription of a submodule project and one of its branches for
-a branch of a super project.
+Gerrit has a complex access control system, where different repositories
+can be accessed by different groups of people. To ensure that the submodule
+related information is allowed to be exposed in the superproject,
+the submodule needs to be configured to enable the superproject subscription.
+In a submodule client, checkout the refs/meta/config branch and edit
+the subscribe capabilities in the 'project.config' file:
+----
+    git fetch <remote> refs/meta/config:refs/meta/config
+    git checkout refs/meta/config
+    $EDITOR project.config
+----
+and add the following lines:
+----
+  [allowSuperproject "<superproject>"]
+    matching = <refspec>
+----
+where the 'superproject' should be the exact project name of the superproject.
+The refspec defines which branches of the submodule are allowed to be
+subscribed to which branches of the superproject. See below for
+link:#acl_refspec[details]. Push the configuration for review and
+submit the change:
+----
+  git add project.config
+  git commit -m "Allow <superproject> to subscribe"
+  git push <remote> HEAD:refs/for/refs/meta/config
+----
+After the change is integrated a superproject subscription is possible.
+
+The configuration is inherited from parent projects, such that you can have
+a configuration in the "All-Projects" project like:
+----
+    [allowSuperproject "my-only-superproject"]
+        matching = refs/heads/*:refs/heads/*
+----
+and then you don't have to worry about configuring the individual projects
+any more. Child projects cannot negate the parent's configuration.
+
+=== Defining the submodule branch
 
 Since Gerrit manages subscriptions in the branch scope, we could have
 a scenario having a project called 'super' having a branch 'integration'
-subscribed to a project called 'a' in branch 'integration', and also
-having the same 'super' project but in branch 'dev' subscribed to the 'a'
+subscribed to a project called 'sub' in branch 'integration', and also
+having the same 'super' project but in branch 'dev' subscribed to the 'sub'
 project in a branch called 'local-dev'.
 
 After adding the git submodule to a super project, one should edit
 the .gitmodules file to add a branch field to each submodule
 section which is supposed to be subscribed.
 
-As the branch field is a Gerrit specific field it will not be filled
+As the branch field is a Gerrit-specific field it will not be filled
 automatically by the git submodule command, so one needs to edit it
 manually. Its value should indicate the branch of a submodule project
 that when updated will trigger automatic update of its registered
@@ -90,45 +139,78 @@
 .gitmodules file, Gerrit will not create a subscription for the
 submodule and there will be no automatic updates to the superproject.
 
-=== Detecting and Subscribing Submodules
+Whenever a commit is merged to a project, its project config is checked
+to see if any potential superprojects are allowed to subscribe to it.
+If so, the superproject is checked if a valid subscription exists
+by checking the .gitmodules file for the a submodule which includes
+a `branch` field and a url pointing to this server.
 
-Whenever a commit is merged to a project, its content is scanned
-to identify if it registers any submodules (if the commit contains new
-gitlinks and a .gitmodules file with all required info) and if so,
-a new submodule subscription is registered.
+[[acl_refspec]]
+=== The RefSpec in the allowSuperproject section
+There are two options for specifying which branches can be subscribed
+to. The most common is to set `allowSuperproject.<superproject>.matching`
+to a Git-style refspec, which has the same syntax as the refspecs used
+for pushing in Git. Regular expressions as found in the ACL configuration
+are not supported.
 
-[[automatic_update]]
-== Automatic Update of Superprojects
+The most restrictive refspec is allowing one specific branch of the
+submodule to be subscribed to one specific branch of the superproject:
+----
+  [allowSuperproject "<superproject>"]
+    matching = refs/heads/<submodule-branch>:refs/heads/<superproject-branch>
+----
 
-After a superproject is subscribed to a submodule, it is not
-required to push/merge commits to this superproject to update the
-gitlink to the submodule.
+If you want to allow for a 1:1 mapping, i.e. 'master' maps to 'master',
+'stable' maps to 'stable', but not allowing 'master' to be subscribed to
+'stable':
+----
+  [allowSuperproject "<superproject>"]
+    matching = refs/heads/*:refs/heads/*
+----
 
-Whenever a commit is merged in a submodule, its subscribed superproject
-is updated.
+To allow all refs matching one pattern to subscribe to all refs
+matching another pattern, set `allowSuperproject.<superproject>.all`
+to the patterns concatenated with a colon. For example, to make a
+single branch available for subscription from all branches of the
+superproject:
+----
+  [allowSuperproject "<superproject>"]
+     all = refs/heads/<submodule-branch>:refs/heads/*
+----
 
-Imagine a superproject called 'super' having a branch called 'dev'
-having subscribed to a submodule 'a' on a branch 'dev-of-a'. When a commit
-is merged in branch 'dev-of-a' of 'a' project, Gerrit automatically
-creates a new commit on branch 'dev' of 'super' updating the gitlink
-to point to the just merged commit.
+To make all branches available for subscription from all branches of
+the superproject:
+----
+  [allowSuperproject "<superproject>"]
+     all = refs/heads/*:refs/heads/*
+----
 
 === Subscription Limitations
 
 Gerrit will only automatically update superprojects where the
 submodules are hosted on the same Gerrit instance as the
-superproject. Gerrit determines this by checking the hostname of the
-submodule specified in the .gitmodules file and comparing it to the
-hostname from the canonical web URL.
+superproject. Gerrit determines this by checking that the URL of the
+submodule specified in the .gitmodules file starts with
+link:config-gerrit.html#gerrit.canonicalWebUrl[`gerrit.canonicalWebUrl`].
+The protocol part is ignored in this check.
 
 It is currently not possible to use the submodule subscription feature
-with a canonical web URL hostname that differs from the hostname of
-the submodule. Instead relative submodules should be used.
+with a canonical web URL that differs from the first part  of
+the submodule URL. Instead relative submodules should be used.
 
-The Gerrit instance administrator group should always certify to
-provide the canonical web URL value in its configuration file. Users
-should certify to use the correct hostname of the running Gerrit
-instance to add/subscribe submodules.
+The Gerrit instance administrator should ensure that the canonical web
+URL value is specified in its configuration file. Users should ensure
+that they use the correct hostname of the running Gerrit instance when
+adding submodule subscriptions.
+
+When converting an existing submodule to use subscription by adding
+a `branch` field into the .gitmodules file, Gerrit does not change
+the revision of the submodule (i.e. update the superproject's gitlink)
+until the next time the branch of the submodule advances. In other words,
+if the currently used revision of the submodule is not the branch's head,
+adding a subscription will not cause an immediate update to the head. In
+this case the revision must be manually updated at the same time as adding
+the subscription.
 
 === Relative submodules
 
@@ -170,10 +252,9 @@
 
 == Removing Subscriptions
 
-If one has added a submodule subscription and drops it, it is
-required to merge a commit updating the subscribed super
-project/branch to remove the gitlink and the submodule section
-of the .gitmodules file.
+To remove a subscription, either disable the subscription from the
+submodules configuration or remove the submodule or information thereof
+(such as the branch field) in the superproject.
 
 GERRIT
 ------
diff --git a/Documentation/user-upload.txt b/Documentation/user-upload.txt
index 25665a3..ba3445a 100644
--- a/Documentation/user-upload.txt
+++ b/Documentation/user-upload.txt
@@ -19,11 +19,17 @@
 user must authenticate via HTTP/HTTPS.
 
 When link:config-gerrit.html#auth.gitBasicAuth[gitBasicAuth] is enabled,
-the user is authenticated using standard BasicAuth and credentials validated
-using the randomly generated HTTP password on the `HTTP Password` tab
-in the user settings page or against LDAP when configured for the Gerrit Web UI.
+the user is authenticated using standard BasicAuth. Depending on the value of
+link:#auth.gitBasicAuthPolicy[auth.gitBasicAuthPolicy], credentials are
+validated using:
 
-When gitBasicAuth is not configured, the user's HTTP credentials can be
+* The randomly generated HTTP password on the `HTTP Password` tab
+  in the user settings page if `gitBasicAuthPolicy` is `HTTP`.
+* The LDAP password if `gitBasicAuthPolicy` is `LDAP`
+* Both, the HTTP and the LDAP passwords (in this order) if `gitBasicAuthPolicy`
+  is `HTTP_LDAP`.
+
+When gitBasicAuthPolicy is not `LDAP`, the user's HTTP credentials can be
 accessed within Gerrit by going to `Settings`, and then accessing the `HTTP
 Password` tab.
 
@@ -54,16 +60,16 @@
 If you don't have any keys yet, you can create a new one and protect
 it with a passphrase:
 
-====
+----
   ssh-keygen -t rsa
-====
+----
 
 Then copy the content of the public key file onto your clipboard,
 and paste it into Gerrit's web interface:
 
-====
+----
   cat ~/.ssh/id_rsa.pub
-====
+----
 
 [TIP]
 Users who frequently upload changes will also want to consider
@@ -80,8 +86,7 @@
 to connect to Gerrit's SSHD port.  By default Gerrit runs on
 port 29418, using the same hostname as the web server:
 
-====
-..................................................................
+----
   $ ssh -p 29418 sshusername@hostname
 
     ****    Welcome to Gerrit Code Review    ****
@@ -94,8 +99,7 @@
     git clone ssh://sshusername@hostname:29418/REPOSITORY_NAME.git
 
   Connection to hostname closed.
-..................................................................
-====
+----
 
 In the command above, `sshusername` was configured as `Username` on
 the `Profile` tab of the `Settings` screen.  If it is not set,
@@ -105,10 +109,10 @@
 information URL `http://'hostname'/ssh_info`, and copy the port
 number from the second field:
 
-====
+----
   $ curl http://hostname/ssh_info
   hostname 29418
-====
+----
 
 If you are developing an automated tool to perform uploads to Gerrit,
 let the user supply the hostname or the web address for Gerrit,
@@ -125,17 +129,17 @@
 To create new changes for review, simply push to the project's
 magical `refs/for/'branch'` ref using any Git client tool:
 
-====
+----
   git push ssh://sshusername@hostname:29418/projectname HEAD:refs/for/branch
-====
+----
 
 E.g. `john.doe` can use git push to upload new changes for the
 `experimental` branch of project `kernel/common`, hosted at the
 `git.example.com` Gerrit server:
 
-====
+----
   git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental
-====
+----
 
 Each new commit uploaded by the `git push` client will be
 converted into a change record on the server.  The remote ref
@@ -146,38 +150,89 @@
 notify them of new changes will be automatically sent an email
 message when the push is completed.
 
+[[push_options]]
+=== Push Options
+
+Additional options may be specified when pushing changes.
+
+[[notify]]
+==== Email Notifications
+
+Uploaders can control to whom email notifications are sent by setting
+the `notify` option:
+
+* `NONE`: No email notification will be sent to anyone.
+* `OWNER`: Only the change owner is notified.
+* `OWNER_REVIEWERS`: Only owners and reviewers will be  notified. This
+  includes all reviewers, existing reviewers of the change and new
+  reviewers that are added by the `reviewer` option or by mentioning
+  in the commit message.
+* `ALL`: All email notifications will be sent. This includes
+  notifications to watchers, users that have starred the change, CCs
+  and the committer and author of the uploaded commit.
+
+By default all email notifications are sent.
+
+----
+  git push ssh://bot@git.example.com:29418/kernel/common HEAD:refs/for/master%notify=NONE
+----
+
 [[topic]]
+==== Topic
+
 To include a short tag associated with all of the changes in the
 same group, such as the local topic branch name, append it after
 the destination branch name. In this example the short topic tag
 'driver/i42' will be saved on each change this push creates or
 updates:
 
-====
+----
   git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%topic=driver/i42
-====
+----
+
+[[message]]
+==== Message
+
+A comment message can be applied to the change by using the `message` (or `m`)
+option:
+
+----
+  git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%m=This_is_a_rebase_on_master
+----
+
+[NOTE]
+git push refs parameter does not allow spaces.  Use the '_' character instead,
+it will then be applied as "This is a rebase on master".
 
 [[review_labels]]
+==== Review Labels
+
 Review labels can be applied to the change by using the `label` (or `l`)
 option in the reference:
 
-====
+----
   git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%l=Verified+1
-====
+----
 
 The `l='label[score]'` option may be specified more than once to
 apply multiple review labels.
 
+----
+  git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/experimental%l=Code-Review+1,l=Verified+1
+----
+
 The value is optional.  If not specified, it defaults to +1 (if
 the label range allows it).
 
 [[change_edit]]
+==== Change Edits
+
 A change edit can be pushed by specifying the `edit` (or `e`) option on
 the reference:
 
-====
+----
   git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%edit
-====
+----
 
 There is at most one change edit per user and change. In order to push
 a change edit the change must already exist.
@@ -193,7 +248,7 @@
 your username, hostname and port number.  This permits the use of
 shorter URLs on the command line, such as:
 
-====
+----
   $ cat ~/.ssh/config
   ...
   Host tr
@@ -202,15 +257,18 @@
     User john.doe
 
   $ git push tr:kernel/common HEAD:refs/for/experimental
-====
+----
+
+[[reviewers]]
+==== Reviewers
 
 Specific reviewers can be requested and/or additional 'carbon
 copies' of the notification message may be sent by including the
 `reviewer` (or `r`) and `cc` options in the reference:
 
-====
+----
   git push tr:kernel/common HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com
-====
+----
 
 The `r='email'` and `cc='email'` options may be specified as many
 times as necessary to cover all interested parties. Gerrit will
@@ -222,7 +280,7 @@
 branches, consider adding a custom remote block to your project's
 `.git/config` file:
 
-====
+----
   $ cat .git/config
   ...
   [remote "exp"]
@@ -230,7 +288,7 @@
     push = HEAD:refs/for/experimental%r=a@a.com,cc=b@o.com
 
   $ git push exp
-====
+----
 
 
 [[push_replace]]
@@ -254,8 +312,8 @@
 [[manual_replacement_mapping]]
 ==== Manual Replacement Mapping
 
-.Note
-****
+[NOTE]
+--
 The remainder of this section describes a manual method of replacing
 changes by matching each commit name to an existing change number.
 End-users should instead prefer to use Change-Id lines in their
@@ -263,7 +321,7 @@
 during normal uploads.
 
 See above for the preferred technique of replacing changes.
-****
+--
 
 To add an additional patch set to a change, replacing it with an
 updated version of the same logical modification, send the new
@@ -271,9 +329,9 @@
 SHA-1 starts with `c0ffee` as a new patch set for change number
 `1979`, use the push refspec `c0ffee:refs/changes/1979` as below:
 
-====
+----
   git push ssh://sshusername@hostname:29418/projectname c0ffee:refs/changes/1979
-====
+----
 
 This form can be combined together with `refs/for/'branchname'`
 (above) to simultaneously create new changes and replace changes
@@ -281,7 +339,7 @@
 
 For example, consider the following sequence of events:
 
-====
+----
   $ git commit -m A                    ; # create 3 commits
   $ git commit -m B
   $ git commit -m C
@@ -298,7 +356,7 @@
       HEAD~3:refs/changes/1500
       HEAD~1:refs/changes/1501
       HEAD~0:refs/changes/1502         ; # upload replacements
-====
+----
 
 At the final step during the push Gerrit will attach A' as a new
 patch set on change 1500; B' as a new patch set on change 1501; C'
@@ -363,18 +421,21 @@
 Changes can be directly submitted on push.  This is primarily useful
 for teams that don't want to do code review but want to use Gerrit's
 submit strategies to handle contention on busy branches.  Using
-`%submit` creates a change and submits it immediately, if the caller
-has link:access-control.html#category_submit[Submit] permission on
-`refs/for/<ref>` (e.g. on `refs/for/refs/heads/master`).
+`%submit` creates a change and submits it immediately:
 
-====
+----
   git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%submit
-====
+----
 
 On auto-merge of a change neither labels nor submit rules are checked.
 If the merge fails the change stays open, but when pushing a new patch
 set the merge can be reattempted by using `%submit` again.
 
+This requires the caller to have link:access-control.html#category_submit[Submit]
+permission on `refs/for/<ref>` (e.g. on `refs/for/refs/heads/master`).
+Note how this is different from the `Submit` permission on `refs/heads/<ref>`,
+and in particular you typically do not want to apply the `Submit` permission
+on `refs/*` (unless you are ok with bypassing submit rules).
 
 [[base]]
 === Selecting Merge Base
@@ -384,18 +445,18 @@
 may override that behavior and force new changes to be created
 by setting the merge base SHA-1 using the '%base' argument:
 
-====
+----
   git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%base=$(git rev-parse origin/master)
-====
+----
 
 It is also possible to specify more than one '%base' argument.
 This may be useful when pushing a merge commit. Note that the '%'
 character has only to be provided once, for the first '%base'
 argument:
 
-====
+----
   git push ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master%base=commit-id1,base=commit-id2
-====
+----
 
 
 == repo upload
diff --git a/README.md b/README.md
index b8de6e2..020602f 100644
--- a/README.md
+++ b/README.md
@@ -71,9 +71,3 @@
 
 _NOTE: release is optional. Last released package of the version is installed if the release
 number is omitted._
-
-## Events
-
-- November 7-8 2015: Gerrit User Conference, Mountain View. ([Register](http://goo.gl/forms/fifi2YQTc7)).
-- November 9-13 2015: Gerrit Hackathon, Mountain View. (Invitation Only).
-- March 2016: Gerrit Hackathon, Berlin. (Details to be confirmed).
diff --git a/ReleaseNotes/BUCK b/ReleaseNotes/BUCK
new file mode 100644
index 0000000..0f47808
--- /dev/null
+++ b/ReleaseNotes/BUCK
@@ -0,0 +1,19 @@
+include_defs('//Documentation/asciidoc.defs')
+include_defs('//ReleaseNotes/config.defs')
+
+DIR = 'ReleaseNotes'
+
+SRCS = glob(['*.txt'])
+
+
+genasciidoc(
+  name = 'html',
+  out = 'html.zip',
+  directory = DIR,
+  srcs = SRCS,
+  attributes = release_notes_attributes(),
+  backend = 'html5',
+  searchbox = False,
+  resources = False,
+  visibility = ['PUBLIC'],
+)
diff --git a/ReleaseNotes/Makefile b/ReleaseNotes/Makefile
deleted file mode 100644
index 3081600..0000000
--- a/ReleaseNotes/Makefile
+++ /dev/null
@@ -1,47 +0,0 @@
-# Copyright (C) 2010 The Android Open Source Project
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-ASCIIDOC       ?= asciidoc
-ASCIIDOC_EXTRA ?=
-
-DOC_HTML      := $(patsubst %.txt,%.html,$(wildcard ReleaseNotes*.txt))
-
-all: html
-
-html: index.html $(DOC_HTML)
-
-clean:
-	rm -f *.html
-
-index.html: index.txt
-	@echo FORMAT $@
-	@rm -f $@+ $@
-	@$(ASCIIDOC) --unsafe \
-		-a toc \
-		-b xhtml11 -f asciidoc.conf \
-		$(ASCIIDOC_EXTRA) -o $@+ $<
-	@mv $@+ $@
-
-$(DOC_HTML): %.html : %.txt
-	@echo FORMAT $@
-	@rm -f $@+ $@
-	@v=$$(echo $< | sed 's/^ReleaseNotes-//;s/.txt$$//;') && \
-	 n=$$(git describe HEAD) && \
-	 if ! git diff-index --quiet v$$v -- $< 2>/dev/null; then v="$$v (from $$n)"; fi && \
-	 $(ASCIIDOC) --unsafe \
-		-a toc \
-		-a "revision=$$v" \
-		-b xhtml11 -f asciidoc.conf \
-		$(ASCIIDOC_EXTRA) -o $@+ $<
-	@mv $@+ $@
diff --git a/ReleaseNotes/ReleaseNotes-2.0.10.txt b/ReleaseNotes/ReleaseNotes-2.0.10.txt
index 695be4f..33078d9 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.10.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.10.txt
@@ -1,13 +1,11 @@
-Release notes for Gerrit 2.0.10
-===============================
+= Release notes for Gerrit 2.0.10
 
 Gerrit 2.0.10 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
 
-New Features
-------------
+== New Features
 
 * GERRIT-129  Make the browser window title reflect the current scre...
 +
@@ -25,8 +23,7 @@
 +
 Minor enhancement to the way submitted emails are formatted.
 
-Bug Fixes
----------
+== Bug Fixes
 
 * GERRIT-91   Delay updating the UI until a Screen instance is fully...
 +
@@ -46,8 +43,7 @@
 * GERRIT-135  Enable Save button after paste in a comment editor
 * GERRIT-137  Error out if a user forgets to squash when replacing a...
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.10 development
 * Add missing super.onSign{In,Out} calls to ChangeScreen
 * Remove the now pointless sign in callback support
diff --git a/ReleaseNotes/ReleaseNotes-2.0.11.txt b/ReleaseNotes/ReleaseNotes-2.0.11.txt
index 62f2a18..5bd6ca0 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.11.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.11.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.0.11
-===============================
+= Release notes for Gerrit 2.0.11
 
 Gerrit 2.0.11 is now available in the usual location:
 
@@ -12,11 +11,9 @@
   java -jar gerrit.war --cat sql/upgrade009_010.sql | psql reviewdb
 ----
 
-Important Notes
----------------
+== Important Notes
 
-Cache directory
-~~~~~~~~~~~~~~~
+=== Cache directory
 
 Gerrit now prefers having a temporary directory to store a disk-based content cache.  This cache used to be in the PostgreSQL database, and was the primary reason for the rather large size of the Gerrit schema.  In 2.0.11 the cache has been moved to the local filesystem, and now has automatic expiration management to prevent it from growing too large.  As this is only a cache, making backups of this directory is not required.
 
@@ -30,13 +27,11 @@
 
 link:http://gerrit.googlecode.com/svn/documentation/2.0/config-gerrit.html[http://gerrit.googlecode.com/svn/documentation/2.0/config-gerrit.html]
 
-Protocol change
-~~~~~~~~~~~~~~~
+=== Protocol change
 
 The protocol between the browser based JavaScript and the server has changed.  After installing 2.0.11 users need to load the site page again to ensure they are running 2.0.11 or later.  Users can verify they have the new version by checking the version number in the footer in the lower right.  Users who don't load the new version (e.g. are using a stale tab from a week ago) will see errors when trying to view patches.
 
-New Features
-------------
+== New Features
 
 * GERRIT-8    Add 'Whole File' as a context preference in the user s...
 * GERRIT-9    Honor user's "Default Context" preference
@@ -65,8 +60,7 @@
 +
 Simple DWIMery: users can now do `repo upload --reviewer=who` to have the reviewer email automatically expand according to the email_format column in system_config, e.g. by expanding `who` to `who@example.com`.
 
-Bug Fixes
----------
+== Bug Fixes
 
 * GERRIT-81   Can't repack a repository while Gerrit is running
 +
@@ -80,8 +74,7 @@
 +
 Service users created by manually inserting into the accounts table didn't permit using their preferred_email in commits or tags; administrators had to also insert a dummy record into the account_external_ids table.  The dummy account_external_ids record is no longer necessary.
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.11 development
 * Include the 'Google Format' style we selected in our p...
 * Upgrade JGit to v0.4.0-310-g3da8761
diff --git a/ReleaseNotes/ReleaseNotes-2.0.12.txt b/ReleaseNotes/ReleaseNotes-2.0.12.txt
index eb28e2e..0e1df04 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.12.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.12.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.0.12
-===============================
+= Release notes for Gerrit 2.0.12
 
 Gerrit 2.0.12 is now available in the usual location:
 
@@ -12,21 +11,17 @@
   java -jar gerrit.war --cat sql/upgrade010_011.sql | psql reviewdb
 ----
 
-Important Notes
----------------
+== Important Notes
 
-Java 6 Required
-~~~~~~~~~~~~~~~
+=== Java 6 Required
 
 Gerrit now requires running within a Java 6 (or later) JVM.
 
-Protocol change
-~~~~~~~~~~~~~~~
+=== Protocol change
 
 The protocol between the browser based JavaScript and the server has changed.  After installing 2.0.12 users need to load the site page again to ensure they are running 2.0.12 or later.  Users can verify they have the new version by checking the version number in the footer in the lower right.  Users who don't load the new version (e.g. are using a stale tab from a week ago) will see errors when trying to view patches.
 
-New Features
-------------
+== New Features
 * Honor --reviewer=not.preferred.email during upload
 * Also scan by preferred email for --reviewers and --cc ...
 +
@@ -73,8 +68,7 @@
 +
 Keyboard bindings have been completely overhauled in this release, and should now work on every browser.  Press '?' in any context to see the available actions.  Please note that this help is context sensitive, so you will only see keys that make sense in the current context.  Actions in a user dashboard screen differ from actions in a patch (for example), but where possible the same key is used when the logical meaning is unchanged.
 
-Bug Fixes
----------
+== Bug Fixes
 * Ignore "SshException: Already closed" errors
 +
 Hides some non-errors from the log file.
@@ -83,8 +77,7 @@
 +
 Should be a minor improvement for MSIE 6 users.
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.12 development
 * Report what version we want on a schema version mismat...
 * Remove unused imports in SshServlet
diff --git a/ReleaseNotes/ReleaseNotes-2.0.13.txt b/ReleaseNotes/ReleaseNotes-2.0.13.txt
index 8ec13a8..7589568 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.13.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.13.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.0.13, 2.0.13.1
-=========================================
+= Release notes for Gerrit 2.0.13, 2.0.13.1
 
 Gerrit 2.0.13.1 is now available in the usual location:
 
@@ -23,8 +22,7 @@
   java -jar gerrit.war --cat sql/upgrade011_012_part2.sql | psql reviewdb
 ----
 
-Configuration Mapping
----------------------
+== Configuration Mapping
 || *system_config*                || *$site_path/gerrit.config*     ||
 || max_session_age                || auth.maxSessionAge             ||
 || canonical_url                  || gerrit.canonicalWebUrl         ||
@@ -45,8 +43,7 @@
 
 See also [http://gerrit.googlecode.com/svn/documentation/2.0/config-gerrit.html Gerrit2 Configuration].
 
-New Features
-------------
+== New Features
 * GERRIT-180  Rewrite outgoing email to be more user friendly
 +
 A whole slew of feature improvements on outgoing email formatting was closed by this one (massive) rewrite of the outgoing email implementation.
@@ -81,8 +78,7 @@
 +
 The new `sendemail` section of `$site_path/gerrit.config` now controls the configuration of the outgoing SMTP server, rather than relying upon a JNDI resource.  See [http://gerrit.googlecode.com/svn/documentation/2.0/config-gerrit.html configuration] section sendemail for more details.
 
-Bug Fixes
----------
+== Bug Fixes
 * Fix file browser in patch that is taller than the wind...
 * GERRIT-184  Make 'f' toggle the file browser popup closed
 * GERRIT-188  Fix key bindings in patch when changing the old or new...
@@ -123,8 +119,7 @@
 +
 Bug fixes identified after release of 2.0.13, rolled into 2.0.13.1.
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.13 development
 * Use gwtexpui 1.1.1-SNAPSHOT
 * Document the Patch.PatchType and Patch.ChangeType enum
diff --git a/ReleaseNotes/ReleaseNotes-2.0.14.txt b/ReleaseNotes/ReleaseNotes-2.0.14.txt
index de58035..128036d 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.14.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.14.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.0.14, 2.0.14.1
-=========================================
+= Release notes for Gerrit 2.0.14, 2.0.14.1
 
 Gerrit 2.0.14.1 is now available in the usual location:
 
@@ -13,8 +12,7 @@
   java -jar gerrit.war --cat sql/upgrade012_013_mysql.sql | mysql reviewdb
 ----
 
-New Features
-------------
+== New Features
 * GERRIT-177  Display branch name next to project in change list
 +
 Now its easier to see from your Mine>Changes what branch each change goes to.  For some users this may help prioritize reviews.
@@ -53,8 +51,7 @@
 +
 This is really for the server admin, the Git reflogs are now more likely to contain actual user information in them, rather than generic "gerrit2@localhost" identities.  This may help if you are mining "WTF happened to this branch" data from Git directly.
 
-Bug Fixes
----------
+== Bug Fixes
 * GERRIT-213  Fix n/p on a file with only one edit
 * GERRIT-66   Always show comments in patch views, even if no edit e...
 * Correctly handle comments after last hunk of patch
@@ -81,8 +78,7 @@
 +
 Fixed run-on addresses when more than one user was listed in To/CC headers.
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.14 development (again)
 * Small doc updates.
 * Merge change 10282
diff --git a/ReleaseNotes/ReleaseNotes-2.0.15.txt b/ReleaseNotes/ReleaseNotes-2.0.15.txt
index a87cba1..a8d60a4 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.15.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.15.txt
@@ -1,23 +1,19 @@
-Release notes for Gerrit 2.0.15
-===============================
+= Release notes for Gerrit 2.0.15
 
 Gerrit 2.0.15 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Schema Change
--------------
+== Schema Change
 
 None.  For a change.  :-)
 
-New Features
-------------
+== New Features
 * Allow other ignore whitespace settings beyond IGNORE_S...
 +
 Now you can ignore whitespace inside the middle of a line, in addition to on the ends.
 
-Bug Fixes
----------
+== Bug Fixes
 * Update SSHD to include SSHD-28 (deadlock on close) bug...
 +
 Fixes a major stability problem with the internal SSHD.  Without this patch the daemon can become unresponsive, requiring a complete JVM restart to recover the daemon.  The symptom is connections appear to work sporadically... some connections are fine while others freeze during setup, or during data transfer.
@@ -31,8 +27,7 @@
 +
 Stupid bugs in the patch viewing code.  Random server errors and/or client UI crashes.
 
-Other Changes
--------------
+== Other Changes
 * Restart 2.0.15 development
 * Update JGit to 0.4.0-411-g8076bdb
 * Remove dead isGerrit method from AbstractGitCommand
diff --git a/ReleaseNotes/ReleaseNotes-2.0.16.txt b/ReleaseNotes/ReleaseNotes-2.0.16.txt
index 4d0252d..4f5a5ba 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.16.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.16.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.0.16
-===============================
+= Release notes for Gerrit 2.0.16
 
 Gerrit 2.0.16 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Schema Change
--------------
+== Schema Change
 
 *WARNING: This version contains a schema change* (since 2.0.14)
 
@@ -16,8 +14,7 @@
   java -jar gerrit.war --cat sql/upgrade013_014_mysql.sql | mysql reviewdb
 ----
 
-New Features
-------------
+== New Features
 * Search for changes created or reviewed by a user
 +
 The search box in the upper right corner now accepts "owner:email" and "reviewer:email", in addition to change numbers and commit SHA-1s.  Using owner: and reviewer: is not the most efficient query plan, as potentially the entire database is scanned.  We hope to improve on that as we move to a pure git based backend.
@@ -42,8 +39,7 @@
 +
 The "/Gerrit" suffix is no longer necessary in the URL.  Gerrit now favors just "/" as its path location.  This drops one redirection during initial page loading, slightly improving page loading performance, and making all URLs 6 characters shorter.  :-)
 
-Bug Fixes
----------
+== Bug Fixes
 * Don't create reflogs for patch set refs
 +
 Previously Gerrit created pointless 1 record reflogs for each change ref under refs/changes/.  These waste an inode on the local filesystem and provide no metadata value, as the same information is also stored in the metadata database.  These reflogs are no longer created.
@@ -64,8 +60,7 @@
 +
 If the hostname is "localhost" or "127.0.0.1", such as might happen when a user tries to proxy through an SSH tunnel, we honor the hostname anyway if OpenID is not being used.
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.16 development
 * Update JGit to 0.4.9-18-g393ad45
 * Name replication threads by their remote name
diff --git a/ReleaseNotes/ReleaseNotes-2.0.17.txt b/ReleaseNotes/ReleaseNotes-2.0.17.txt
index 493a64b..8a24b22 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.17.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.17.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.0.17
-===============================
+= Release notes for Gerrit 2.0.17
 
 Gerrit 2.0.17 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Schema Change
--------------
+== Schema Change
 
 *WARNING: This version contains a schema change* (since 2.0.16)
 
@@ -22,8 +20,7 @@
   java -jar gerrit.war --cat sql/upgrade014_015_part2.sql | mysql reviewdb
 ----
 
-New Features
-------------
+== New Features
 * Add '[' and ']' shortcuts to PatchScreen.
 +
 The keys '[' and ']' can be used to navigate to previous and next file in a patch set.
@@ -56,8 +53,7 @@
 +
 The owner of a project was moved from the General tab to the Access Rights tab, under a new category called Owner.  This permits multiple groups to be designated the Owner of the project (simply grant Owner status to each group).
 
-Bug Fixes
----------
+== Bug Fixes
 * Permit author Signed-off-by to be optional
 +
 If a project requires Signed-off-by tags to appear the author tag is now optional, only the committer/uploader must provide a Signed-off-by tag.
@@ -83,8 +79,7 @@
 +
 Instead of crashing on a criss-cross merge case, Gerrit unsubmits the change and attaches a message, like it does when it encounters a path conflict.
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.17 development
 * Move '[' and ']' key bindings to Navigation category
 * Use gwtexpui 1.1.2-SNAPSHOT to fix navigation keys
diff --git a/ReleaseNotes/ReleaseNotes-2.0.18.txt b/ReleaseNotes/ReleaseNotes-2.0.18.txt
index df635d9..1028185 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.18.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.18.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.0.18
-===============================
+= Release notes for Gerrit 2.0.18
 
 Gerrit 2.0.18 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Important Notices
------------------
+== Important Notices
 
 Please ensure you read the following important notices about this release; .18 is a much larger release than usual.
 
@@ -41,8 +39,7 @@
 the SSH authentication system.  More details can be found in the
 [http://android.git.kernel.org/?p=tools/gerrit.git;a=commit;h=080b40f7bbe00ac5fc6f2b10a861b63ce63e8add commit message].
 
-Schema Change
--------------
+== Schema Change
 
 *WARNING: This version contains a schema change* (since 2.0.17)
 
@@ -71,15 +68,13 @@
   java -jar gerrit.war --cat sql/upgrade015_016_part2.sql | mysql reviewdb
 ----
 
-New Bugs
---------
+== New Bugs
 * Memory leaks during warm restarts
 
 2.0.18 includes [http://code.google.com/p/google-guice/ Google Guice], which leaves a finalizer thread dangling when the Gerrit web application is halted by the servlet container.  As this thread does not terminate, the web context stays loaded in memory indefinitely, creating a memory leak.  Cold restarting the container in order to restart Gerrit is highly recommended.
 
 
-New Features
-------------
+== New Features
 * GERRIT-104  Allow end-users to select their own SSH username
 +
 End users may now select their own SSH username through the web interface.  The username must be unique within a Gerrit server installation.  During upgrades from 2.0.17 duplicate users are resolved by giving the username to the user who most recently logged in under it; other users will need to login through the web interface and select a unique username.  This change was necessary to fix a very minor security bug (see above).
@@ -113,8 +108,7 @@
 +
 As noted above in the section about cache changes, the disk cache is now completely optional.
 
-Bug Fixes
----------
+== Bug Fixes
 * GERRIT-5    Remove PatchSetInfo from database and get it always fr...
 +
 A very, very old bug.  We no longer mirror the commit data into the SQL database, but instead pull it directly from Git when needed.  Removing duplicated data simplifies the data store model, something that is important as we shift from an SQL database to a Git backed database.
@@ -139,8 +133,7 @@
 +
 The database schema changed, adding `patch_set_id` to the approval object, and renaming the approval table to `patch_set_approvals`.  If you have external code writing to this table, uh, sorry, its broken with this release, you'll have to update that code first.  :-\
 
-Other Changes
--------------
+== Other Changes
 
 This release is really massive because the internal code moved from some really ugly static data variables to doing almost everything through Guice injection.  Nothing user visible, but code cleanup that needed to occur before we started making additional changes to the system.
 
diff --git a/ReleaseNotes/ReleaseNotes-2.0.19.txt b/ReleaseNotes/ReleaseNotes-2.0.19.txt
index 0e114c8..c9d9c56 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.19.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.19.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.0.19, 2.0.19.1, 2.0.19.2
-===================================================
+= Release notes for Gerrit 2.0.19, 2.0.19.1, 2.0.19.2
 
 Gerrit 2.0.19.2 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Important Notices
------------------
+== Important Notices
 
 * Prior User Sessions
 +
@@ -25,8 +23,7 @@
 set [http://gerrit.googlecode.com/svn/documentation/2.0/config-gerrit.html#cache.directory cache.directory] in gerrit.config.  This allows Gerrit to flush the set
 of active sessions to disk during shutdown, and load them back during startup.
 
-Schema Change
--------------
+== Schema Change
 
 *WARNING: This version contains a schema change* (since 2.0.18)
 
@@ -44,8 +41,7 @@
 ----
 
 
-New Features
-------------
+== New Features
 * New ssh create-project command
 +
 Thanks to Ulrik Sjölin we now have `gerrit create-project`
@@ -171,8 +167,7 @@
 For more details, please see the docs:
 link:http://gerrit.googlecode.com/svn/documentation/2.0/user-changeid.html[http://gerrit.googlecode.com/svn/documentation/2.0/user-changeid.html]
 
-Bug Fixes
----------
+== Bug Fixes
 * Fix yet another ArrayIndexOutOfBounds during side-by-s...
 +
 We found yet another bug with the side-by-side view failing
@@ -230,8 +225,7 @@
 wrong project, e.g. uploading a replacement commit to project
 B while picking a change number from project A.  Fixed.
 
-=Fixes in 2.0.19.1=
--------------------
+== =Fixes in 2.0.19.1=
 
 * Fix NPE during direct push to branch closing a change
 +
@@ -258,8 +252,7 @@
 +
 HTTP_LDAP broke using local usernames to match an account.  Fixed.
 
-=Fixes in 2.0.19.2=
--------------------
+== =Fixes in 2.0.19.2=
 * Don't line wrap project or group names in admin panels
 +
 Line wrapping group names like "All Users" when the description column
@@ -283,8 +276,7 @@
 As reported on repo-discuss, recursive search is sometimes necessary,
 and is now the default.
 
-Removed Features
-----------------
+== Removed Features
 
 * Remove support for /user/email style URLs
 +
@@ -292,8 +284,7 @@
 discoverable.  Its unlikely anyone is really using it, but if
 they are, they could try using "#q,owner:email,n,z" instead.
 
-Other Changes
--------------
+== Other Changes
 
 * Start 2.0.19 development
 * Document the Failure and UnloggedFailure classes in Ba...
diff --git a/ReleaseNotes/ReleaseNotes-2.0.2.txt b/ReleaseNotes/ReleaseNotes-2.0.2.txt
index b2d5b98..eb8546c 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.2.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.2.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.0.2
-==============================
+= Release notes for Gerrit 2.0.2
 
 Gerrit 2.0.2 is now available for download:
 
 link:https://www.gerritcodereview.com/[https://www.gerritcodereview.com/]
 
-Important Notes
----------------
+== Important Notes
 
 Starting with this version, Gerrit is now packaged as a single WAR file.
 Just download and drop into your webapps directory for easier deployment.
@@ -31,16 +29,14 @@
 and insert it into your container's CLASSPATH.  But I think all known
 instances are on PostgreSQL, so this is probably not a concern to anyone.
 
-New Features
-------------
+== New Features
 
 * Trailing whitespace is highlighted in diff views
 * SSHD upgraded with "faster connection" patch discussed on list
 * Git reflogs now contain the Gerrit account information of who did the push
 * Insanely long change subjects are now clipped at 80 characters
 
-All Changes
------------
+== All Changes
 
 * Switch back to -SNAPSHOT builds
 * Overhaul our build system to only create a WAR file
diff --git a/ReleaseNotes/ReleaseNotes-2.0.20.txt b/ReleaseNotes/ReleaseNotes-2.0.20.txt
index 527de8e..4f15bb0 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.20.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.20.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.0.20
-===============================
+= Release notes for Gerrit 2.0.20
 
 Gerrit 2.0.20 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Schema Change
--------------
+== Schema Change
 
 A prior bug (GERRIT-262) permitted some invalid data to enter into some databases.  Administrators should consider running the following update statement as part of their upgrade to .20 to make any comments which were created with this bug visible:
 ----
@@ -14,8 +12,7 @@
 ----
 Unfortunately the correct position of the comment has been lost, and the statement above will simply position them on the first line of the file.  Fortunately the lost comments were only on the wrong side of an insertion or deletion, and are generally rare.  (On my servers only 0.33% of the comments were created like this.)
 
-New Features
-------------
+== New Features
 * New ssh command approve
 +
 Patch sets can now be approved remotely via SSH.  For more
@@ -31,8 +28,7 @@
 administrators may permit automatically updating an existing
 account with a new identity by matching on the email address.
 
-Bug Fixes
----------
+== Bug Fixes
 * GERRIT-262  Disallow creating comments on line 0
 +
 Users were able to create comments in dead regions of a file.
@@ -59,8 +55,7 @@
 +
 MySQL schema upgrade scripts had a few bugs, fixed.
 
-Other Changes
--------------
+== Other Changes
 * Restart 2.0.20
 * Update MINA SSHD to 0.2.0 release
 * Update args4j to snapshot built from current CVS
diff --git a/ReleaseNotes/ReleaseNotes-2.0.21.txt b/ReleaseNotes/ReleaseNotes-2.0.21.txt
index 34ab581..5de84ff 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.21.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.21.txt
@@ -1,13 +1,11 @@
-Release notes for Gerrit 2.0.21
-===============================
+= Release notes for Gerrit 2.0.21
 
 Gerrit 2.0.21 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
 
-Schema Change
--------------
+== Schema Change
 
 *WARNING: This version contains a schema change* (since 2.0.19)
 
@@ -48,8 +46,7 @@
 ----
 
 
-Important Notices
------------------
+== Important Notices
 
 * Prior User Sessions
 +
@@ -106,8 +103,7 @@
 a supported provider.  I just want to make it clear that I no
 longer recommend it in production.
 
-New Features
-------------
+== New Features
 
 * GERRIT-189  Show approval status in account dashboards
 +
@@ -203,8 +199,7 @@
 to `USER` in gerrit.config.  For more details see
 link:http://gerrit.googlecode.com/svn/documentation/2.0/config-gerrit.html#sendemail.from[sendemail.from]
 
-Bug Fixes
----------
+== Bug Fixes
 
 * Fix ReviewDb to actually be per-request scoped
 +
@@ -276,8 +271,7 @@
 the same email address, or to have the same OpenID auth token.
 Fixed by asserting a unique constraint on the column.
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.21 development
 * Support cleaning up a Commons DBCP connection pool
 * Clarify which Factory we are importing in ApproveComma...
diff --git a/ReleaseNotes/ReleaseNotes-2.0.22.txt b/ReleaseNotes/ReleaseNotes-2.0.22.txt
index faaca81..5e2f8b5 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.22.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.22.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.0.22
-===============================
+= Release notes for Gerrit 2.0.22
 
 Gerrit 2.0.22 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Schema Change
--------------
+== Schema Change
 
 There is no schema change in this release.
 
@@ -32,8 +30,7 @@
    login over SSH until they return and select a new name.
 
 
-New Features
-------------
+== New Features
 * GERRIT-280  create-project: Add --branch and cleanup arguments
 +
 The --branch option to create-project can be used to setup the
@@ -94,8 +91,7 @@
 +
 Sample git pull lines are now included in email notifications.
 
-Bug Fixes
----------
+== Bug Fixes
 * create-project: Document needing to double quote descr...
 +
 The --description flag to create-project require two levels
@@ -141,8 +137,7 @@
 Merge commits created by Gerrit were still using the older style
 integer change number; changed to use the abbreviated Change-Id.
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.22 development
 * Configure Maven to build with UTF-8 encoding
 * Document minimum build requirement for Mac OS X
diff --git a/ReleaseNotes/ReleaseNotes-2.0.23.txt b/ReleaseNotes/ReleaseNotes-2.0.23.txt
index 16488d4..a3f28a7 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.23.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.23.txt
@@ -1,18 +1,15 @@
-Release notes for Gerrit 2.0.23
-===============================
+= Release notes for Gerrit 2.0.23
 
 Gerrit 2.0.23 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Schema Change
--------------
+== Schema Change
 
 There is no schema change in this release.
 
 
-New Features
-------------
+== New Features
 
 * Adding support to list merged and abandoned changes
 +
@@ -22,8 +19,7 @@
 changes in the same project while merged changes link to all merged
 changes in the same project.  These links are bookmarkable.
 
-Bug Fixes
----------
+== Bug Fixes
 
 * Fix new change email to always have SSH pull URL
 * Move git pull URL to bottom of email notifications
@@ -39,8 +35,7 @@
 
 * Fix MySQL CREATE USER example in install documentation
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.23 development
 * Move Jetty 6.x resources into a jetty6 directory
 * Move the Jetty 6.x start script to our extra directory
diff --git a/ReleaseNotes/ReleaseNotes-2.0.24.txt b/ReleaseNotes/ReleaseNotes-2.0.24.txt
index 1f08582..7da1693 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.24.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.24.txt
@@ -1,13 +1,11 @@
-Release notes for Gerrit 2.0.24, 2.0.24.1, 2.0.24.2
-===================================================
+= Release notes for Gerrit 2.0.24, 2.0.24.1, 2.0.24.2
 
 Gerrit 2.0.24 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
 
-Schema Change
--------------
+== Schema Change
 
 *WARNING: This version contains a schema change* (since 2.0.21)
 
@@ -18,8 +16,7 @@
 ----
 
 
-LDAP Change
------------
+== LDAP Change
 
 LDAP groups are now bound via their full distinguished name, and not
 by their common name.  Sites using LDAP groups will need to have the
@@ -34,8 +31,7 @@
 create identically named groups.
 
 
-New Features
-------------
+== New Features
 * Check if the user has permission to upload changes
 +
 The new READ +2 permission is required to upload a change to a
@@ -69,8 +65,7 @@
 Encrypted SMTP is now supported natively within Gerrit, see
 link:http://gerrit.googlecode.com/svn/documentation/2.0/config-gerrit.html#sendemail.smtpEncryption[sendemail.smtpEncryption]
 
-Bug Fixes
----------
+== Bug Fixes
 * issue 290    Fix invalid drop index in upgrade017_018_mysql
 +
 Minor syntax error in SQL script.
@@ -142,8 +137,7 @@
 identities when the claimed identity is just a delegate to the
 delegate provider.  We now store both in the account.
 
-Fixes in 2.0.24.1
------------------
+== Fixes in 2.0.24.1
 * Fix unused import in OpenIdServiceImpl
 * dev-readme: Fix formatting of initdb command
 +
@@ -159,8 +153,7 @@
 Fixes sendemail configuration to use the documented smtppass
 variable and not the undocumented smtpuserpass variable.
 
-Fixes in 2.0.24.2
------------------
+== Fixes in 2.0.24.2
 * Fix CreateSchema to create Administrators group
 * Fix CreateSchema to set type of Registered Users group
 * Default AccountGroup instances to type INTERNAL
@@ -180,8 +173,7 @@
 Added unit tests to validate CreateSchema works properly, so we
 don't have a repeat of breakage here.
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.24 development
 * Merge change Ie16b8ca2
 * Switch to the new org.eclipse.jgit package
diff --git a/ReleaseNotes/ReleaseNotes-2.0.3.txt b/ReleaseNotes/ReleaseNotes-2.0.3.txt
index 6bf3510..d319b35 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.3.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.3.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.0.3
-==============================
+= Release notes for Gerrit 2.0.3
 
 Gerrit 2.0.3 is now available in the usual location:
 
@@ -10,8 +9,7 @@
 existing change".  This has been an open issue in the bug tracker for a
 while, and its finally closed thanks to his work.
 
-New Features
-------------
+== New Features
 
 * GERRIT-37  Add additional reviewers to an existing change
 * Display old and new image line numbers in unified diff
@@ -19,8 +17,7 @@
 * Allow up/down arrow keys to scroll the page in patch view
 * Use a Java applet to help users load public SSH keys
 
-Bug Fixes
----------
+== Bug Fixes
 
 * GERRIT-72  Make review comments standout more from the surrounding text
 * GERRIT-7   Restart the merge queue when Gerrit starts up
@@ -36,8 +33,7 @@
 Gerrit UI.  Such a display might be able to convince a user they are
 clicking on one thing, while doing something else entirely.
 
-Other Changes
--------------
+== Other Changes
 
 * Restore -SNAPSHOT suffix after 2.0.2
 * Add a document describing Gerrit's high level design
diff --git a/ReleaseNotes/ReleaseNotes-2.0.4.txt b/ReleaseNotes/ReleaseNotes-2.0.4.txt
index fec2425..0b10756 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.4.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.4.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.0.4
-==============================
+= Release notes for Gerrit 2.0.4
 
 Gerrit 2.0.4 is now available in the usual location:
 
@@ -31,8 +30,7 @@
 individual user's privacy by strongly encrypting their contact
 information, and storing it "off site".
 
-Other Changes
--------------
+== Other Changes
 * Change to 2.0.3-SNAPSHOT
 * Correct grammar in the patch conflict messages
 * Document how to create branches through SSH and web
diff --git a/ReleaseNotes/ReleaseNotes-2.0.5.txt b/ReleaseNotes/ReleaseNotes-2.0.5.txt
index 70116d3..8006e12 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.5.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.5.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.0.5
-==============================
+= Release notes for Gerrit 2.0.5
 
 Gerrit 2.0.5 is now available in the usual location:
 
@@ -15,8 +14,7 @@
 
 link:http://gerrit.googlecode.com/svn/documentation/2.0/config-sso.html[http://gerrit.googlecode.com/svn/documentation/2.0/config-sso.html]
 
-New Features
-------------
+== New Features
 
 * GERRIT-62  Work around IE6's inability to set innerHTML on a tbody ...
 * GERRIT-62  Upgrade to gwtjsonrpc 1.0.2 for ie6 support
@@ -35,14 +33,12 @@
 +
 These features make it easier to copy patch download commands.
 
-Bug Fixes
----------
+== Bug Fixes
 
 * GERRIT-79  Error out with more useful message on "push :refs/change...
 * Invalidate all SSH keys when otherwise flushing all cach...
 
-Other Changes
--------------
+== Other Changes
 
 * Set version 2.0.4-SNAPSHOT
 * Correct note in developer setup about building SSHD
diff --git a/ReleaseNotes/ReleaseNotes-2.0.6.txt b/ReleaseNotes/ReleaseNotes-2.0.6.txt
index 9d0af33..1e28da8 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.6.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.6.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.0.6
-==============================
+= Release notes for Gerrit 2.0.6
 
 Gerrit 2.0.6 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-New Features
-------------
+== New Features
 
 * GERRIT-41  Add support for abandoning a dead change
 +
@@ -14,8 +12,7 @@
 
 * Bold substrings which match query when showing completi...
 
-Bug Fixes
----------
+== Bug Fixes
 
 * GERRIT-43  Work around Safari 3.2.1 OpenID login problems
 * GERRIT-43  Suggest boosting the headerBufferSize when deploying un...
@@ -24,8 +21,7 @@
 * GERRIT-76  Upgrade to JGit 0.4.0-209-g9c26a41
 * Ensure branches modified through web UI replicate
 
-Other Changes
--------------
+== Other Changes
 
 * Start 2.0.6 development
 * Generate the id for the iframe used during OpenID login
diff --git a/ReleaseNotes/ReleaseNotes-2.0.7.txt b/ReleaseNotes/ReleaseNotes-2.0.7.txt
index afc7784..d1bc38f 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.7.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.7.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.0.7
-==============================
+= Release notes for Gerrit 2.0.7
 
 Gerrit 2.0.7 is now available in the usual location:
 
@@ -11,15 +10,13 @@
 
 Gerrit is still Apache 2/MIT/BSD licensed, despite the switch of a dependency.
 
-New Features
-------------
+== New Features
 
 * GERRIT-103  Display our server host keys for the client to copy an...
 +
 For the paranoid user, they can check the key fingerprint, or even copy the complete host key line for ~/.ssh/known_hosts, directly from Settings > SSH Keys.
 
-Bug Fixes
----------
+== Bug Fixes
 
 * GERRIT-98   Require that a change be open in order to abandon it
 * GERRIT-101  Switch OpenID relying party to openid4java
@@ -34,8 +31,7 @@
 
 * Fix a NullPointerException in OpenIdServiceImpl on res...
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.7 development
 * Upgrade JGit to 0.4.0-212-g9057f1b
 * Make the sign in dialog a bit taller to avoid clipping...
diff --git a/ReleaseNotes/ReleaseNotes-2.0.8.txt b/ReleaseNotes/ReleaseNotes-2.0.8.txt
index 4b2d10a5..89e7fdd 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.8.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.8.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.0.8
-==============================
+= Release notes for Gerrit 2.0.8
 
 Gerrit 2.0.8 is now available in the usual location:
 
@@ -14,8 +13,7 @@
 This version has some major bug fixes for JGit.  I strongly encourage people to upgrade, we had a number of JGit bugs identified last week, all of them should be fixed in this release.
 
 
-New Features
-------------
+== New Features
 * Allow users to subscribe to submitted change events
 +
 Someone asked me on an IRC channel to have Gerrit send emails when changes are actually merged into a project.  This is what triggered the schema change; there is a new checkbox on the Watched Projects list under Settings to subscribe to these email notifications.
@@ -33,15 +31,13 @@
 +
 The reflogs now contain the remote user's IP address when Gerrit makes edits, resulting in slightly more detail than was there before.
 
-Bug Fixes
----------
+== Bug Fixes
 * Make sure only valid ObjectIds can be passed into git d...
 * GERRIT-92  Upgrade JGit to 0.4.0-262-g3c268c8
 +
 The JGit bug fixes are rather major.  I would strongly encourage upgrading.
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.8 development
 * Upgrade MINA SSHD to SVN trunk 755651
 * Fix a minor whitespace error in ChangeMail
diff --git a/ReleaseNotes/ReleaseNotes-2.0.9.txt b/ReleaseNotes/ReleaseNotes-2.0.9.txt
index d2a9196..1f683cf 100644
--- a/ReleaseNotes/ReleaseNotes-2.0.9.txt
+++ b/ReleaseNotes/ReleaseNotes-2.0.9.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.0.9
-==============================
+= Release notes for Gerrit 2.0.9
 
 Gerrit 2.0.9 is now available in the usual location:
 
@@ -20,8 +19,7 @@
 
 The SQL statement to insert a new project into the database has been changed.  Please see [http://gerrit.googlecode.com/svn/documentation/2.0/project-setup.html Project Setup] for the modified statement.
 
-New Features
-------------
+== New Features
 * GERRIT-69   Make the merge commit message more detailed when mergi...
 * Show the user's starred/not-starred icon in the change...
 * Modify Push Annotated Tag to require signed tags, or r...
@@ -34,8 +32,7 @@
 These last two changes move the hidden gerrit.fastforwardonly feature to the database and the user interface, so project owners can make use of it (or not).  Please see the new 'Change Submit Action' section in the user documentation:
 link:http://gerrit.googlecode.com/svn/documentation/2.0/project-setup.html[http://gerrit.googlecode.com/svn/documentation/2.0/project-setup.html]
 
-Bug Fixes
----------
+== Bug Fixes
 * Work around focus bugs in WebKit based browsers
 * Include our license list in the WAR file
 * Whack any prior submit approvals by myself when replac...
@@ -43,8 +40,7 @@
 * GERRIT-85   ie6: Correct rendering of commit messages
 * GERRIT-89   ie6: Fix date line wrapping in messages
 
-Other Changes
--------------
+== Other Changes
 * Start 2.0.9 development
 * Always show the commit SHA-1 next to the patch set hea...
 * Silence more non-critical log messages from openid4java
diff --git a/ReleaseNotes/ReleaseNotes-2.1.1.txt b/ReleaseNotes/ReleaseNotes-2.1.1.txt
index 9d795b6..38b6caf 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.1.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.1.txt
@@ -1,20 +1,17 @@
-Release notes for Gerrit 2.1.1, 2.1.1.1
-=======================================
+= Release notes for Gerrit 2.1.1, 2.1.1.1
 
 Gerrit 2.1.1.1 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Schema Change
--------------
+== Schema Change
 
 *WARNING* This release contains a schema change.  To upgrade:
 ----
   java -jar gerrit.war init -d site_path
 ----
 
-Patch 2.1.1.1
--------------
+== Patch 2.1.1.1
 
 * Update MINA SSHD to SVN 897374
 +
@@ -28,8 +25,7 @@
 Discarding a comment from the publish comments screen caused
 a ConcurrentModificationException.  Fixed.
 
-New Features
-------------
+== New Features
 
 * issue 322    Update to GWT 2.0.0
 +
@@ -106,8 +102,7 @@
 by an accidental click.  This is especially useful when there
 is a merge error during submit.
 
-Bug Fixes
----------
+== Bug Fixes
 
 * issue 359    Allow updates of commits where only the parent changes
 +
@@ -158,8 +153,7 @@
 to leak file descriptors, as pipes to the external CGI were not
 always closed.  Fixed.
 
-Other
------
+== Other
 * Switch to ClientBundle
 * Update to gwtexpui-1.2.0-SNAPSHOT
 * Merge branch 'master' into gwt-2.0
diff --git a/ReleaseNotes/ReleaseNotes-2.1.10.txt b/ReleaseNotes/ReleaseNotes-2.1.10.txt
index 5464267..5c5bcc6 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.10.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.10.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.10
-===============================
+= Release notes for Gerrit 2.1.10
 
 There are no schema changes from link:ReleaseNotes-2.1.9.html[2.1.9].
 
 link:https://www.gerritcodereview.com/download/gerrit-2.1.10.war[https://www.gerritcodereview.com/download/gerrit-2.1.10.war]
 
-Bug Fixes
----------
+== Bug Fixes
 * Fix clone for modern Git clients
 +
 The security fix in 2.1.9 broke clone for recent Git clients,
diff --git a/ReleaseNotes/ReleaseNotes-2.1.2.1.txt b/ReleaseNotes/ReleaseNotes-2.1.2.1.txt
index ae5d912..b181fee 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.2.1.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.2.1.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.2.1
-================================
+= Release notes for Gerrit 2.1.2.1
 
 Gerrit 2.1.2.1 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Bug Fixes
----------
+== Bug Fixes
 
 * Include smart http:// URLs in gitweb
 +
diff --git a/ReleaseNotes/ReleaseNotes-2.1.2.2.txt b/ReleaseNotes/ReleaseNotes-2.1.2.2.txt
index 6565833..305e3e1 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.2.2.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.2.2.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.2.2
-================================
+= Release notes for Gerrit 2.1.2.2
 
 Gerrit 2.1.2.2 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Bug Fixes
----------
+== Bug Fixes
 
 * Add ',' to be encoded in email headers.
 +
diff --git a/ReleaseNotes/ReleaseNotes-2.1.2.3.txt b/ReleaseNotes/ReleaseNotes-2.1.2.3.txt
index 3cfbdd1..f81092c 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.2.3.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.2.3.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.2.3
-================================
+= Release notes for Gerrit 2.1.2.3
 
 Gerrit 2.1.2.3 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Bug Fixes
----------
+== Bug Fixes
 
 * issue 528 gsql: Fix escaping of quotes in JSON
 +
diff --git a/ReleaseNotes/ReleaseNotes-2.1.2.4.txt b/ReleaseNotes/ReleaseNotes-2.1.2.4.txt
index 5e863f7..45fcb40 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.2.4.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.2.4.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.2.4
-================================
+= Release notes for Gerrit 2.1.2.4
 
 Gerrit 2.1.2.4 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-New Features
-------------
+== New Features
 
 * Add 'checkout' download command to patch sets
 +
@@ -14,8 +12,7 @@
 and checkout the patch set on a detached HEAD.  This is more suitable
 for building and testing the change locally.
 
-Bug Fixes
----------
+== Bug Fixes
 
 * issue 545 Fallback to ISO-8859-1 if charset isn't supported
 +
@@ -45,8 +42,7 @@
 in the directory, Gerrit crashed during sign-in while trying to
 clear out the user name.  Fixed.
 
-Documentation Corrections
-~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Documentation Corrections
 
 * documentation: Elaborate on branch level Owner
 +
diff --git a/ReleaseNotes/ReleaseNotes-2.1.2.5.txt b/ReleaseNotes/ReleaseNotes-2.1.2.5.txt
index 6e9a49e..eece1e7 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.2.5.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.2.5.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.2.5
-================================
+= Release notes for Gerrit 2.1.2.5
 
 Gerrit 2.1.2.5 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Bug Fixes
----------
+== Bug Fixes
 
 * issue 390 Resolve objects going missing
 +
diff --git a/ReleaseNotes/ReleaseNotes-2.1.2.txt b/ReleaseNotes/ReleaseNotes-2.1.2.txt
index e0d8c12..8e7cd5c 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.2.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.2.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.2
-==============================
+= Release notes for Gerrit 2.1.2
 
 Gerrit 2.1.2 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Schema Change
--------------
+== Schema Change
 
 *WARNING* This release contains multiple schema changes.  To upgrade:
 ----
@@ -14,8 +12,7 @@
 ----
 
 
-Breakages
----------
+== Breakages
 
 * issue 421 Force validation of the author and committer lines
 +
@@ -33,11 +30,9 @@
 exists, and Forge Identity +2 where Push Branch >= +1 exists.
 
 
-New Features
-------------
+== New Features
 
-UI - Diff Viewer
-~~~~~~~~~~~~~~~~
+=== UI - Diff Viewer
 
 * issue 169 Highlight line-level (aka word) differences in files
 +
@@ -110,8 +105,7 @@
 * Use RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK for tabs
 * Use a tooltip to explain whitespace errors
 
-UI - Other
-~~~~~~~~~~
+=== UI - Other
 
 * issue 408 Show summary of code review, verified on all open changes
 +
@@ -153,8 +147,7 @@
 Site administrators can now theme the UI with local site colors
 by setting theme variables in gerrit.config.
 
-Permissions
-~~~~~~~~~~~
+=== Permissions
 
 * issue 60 Change permissions to be branch based
 +
@@ -172,8 +165,7 @@
 See link:http://gerrit.googlecode.com/svn/documentation/2.1.2/access-control.html#function_MaxNoBlock[access control]
 for more details on this function.
 
-Remote Access
-~~~~~~~~~~~~~
+=== Remote Access
 
 * Enable smart HTTP under /p/ URLs
 +
@@ -210,8 +202,7 @@
 addition to single quotes.  This can make it easier to intermix
 quoting styles with the shell that is calling the SSH client .
 
-Server Administration
-~~~~~~~~~~~~~~~~~~~~~
+=== Server Administration
 
 * issue 383 Add event hook support
 +
@@ -272,8 +263,7 @@
 software driven queries over SSH easier.  The -c option accepts
 one query, executes it, and returns.
 
-Other
-~~~~~
+=== Other
 
 * Warn when a commit message isn't wrapped
 +
@@ -290,11 +280,9 @@
 rather than from the user's preferred account information.
 
 
-Bug Fixes
----------
+== Bug Fixes
 
-UI
-~~
+=== UI
 
 * Change "Publish Comments" to "Review"
 +
@@ -380,8 +368,7 @@
 * Update URL for GitHub's SSH key guide
 * issue 314 Hide group type choice if LDAP is not enabled
 
-Email
-~~~~~
+=== Email
 
 * Send missing dependencies to owners if they are the only reviewer
 +
@@ -401,8 +388,7 @@
 An additional from line is now injected at the start of the email
 body to indicate the actual user.
 
-Remote Access
-~~~~~~~~~~~~~
+=== Remote Access
 
 * issue 385 Delete session cookie when session is expired
 +
@@ -443,8 +429,7 @@
 whitespace, removing a common source of typos that lead to users
 being automatically assigned more than one Gerrit user account.
 
-Server Administration
-~~~~~~~~~~~~~~~~~~~~~
+=== Server Administration
 
 * daemon: Really allow httpd.listenUrl to end with /
 +
@@ -532,8 +517,7 @@
 sometimes failed.  Fixed by executing an implicit reload in these
 cases, reducing the number of times a user sees a failure.
 
-Development
-~~~~~~~~~~~
+=== Development
 
 * issue 427 Adjust SocketUtilTest to be more likely to pass
 +
@@ -569,8 +553,7 @@
 removed from the license file.
 
 
-Schema Changes in Detail
-------------------------
+== Schema Changes in Detail
 
 * Remove Project.Id and use only Project.NameKey
 +
@@ -594,8 +577,7 @@
 aren't possible, or to run on MySQL MyISAM tables.
 
 
-Other Changes
--------------
+== Other Changes
 * Update gwtorm to 1.1.4-SNAPSHOT
 * Add unique column ids to every column
 * Remove unused byName @SecondaryKey from ApprovalCategory
diff --git a/ReleaseNotes/ReleaseNotes-2.1.3.txt b/ReleaseNotes/ReleaseNotes-2.1.3.txt
index f4faf32..6226b93 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.3.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.3.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.3
-==============================
+= Release notes for Gerrit 2.1.3
 
 Gerrit 2.1.3 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Schema Change
--------------
+== Schema Change
 
 *WARNING* This release contains multiple schema changes.  To upgrade:
 ----
@@ -14,11 +12,9 @@
 ----
 
 
-New Features
-------------
+== New Features
 
-Web UI
-~~~~~~
+=== Web UI
 
 * issue 289 Remove reviewers (or self) from a change
 +
@@ -63,8 +59,7 @@
 Access tabs.  Editing is obviously disabled, unless the user has
 owner level access to the project, or one of its branches.
 
-Access Controls
-~~~~~~~~~~~~~~~
+=== Access Controls
 
 * Branch-level read access is now supported
 +
@@ -97,8 +92,7 @@
 inherited by default, but the old exclusive behavior can be obtained
 by prefixing the reference with '-'.
 
-SSH Commands
-~~~~~~~~~~~~
+=== SSH Commands
 
 * create-account: Permit creation of batch user accounts over SSH
 * issue 269 Enable create-project for non-Administrators
@@ -125,8 +119,7 @@
 The old `gerrit approve` name will be kept around as an alias to
 provide time to migrate hooks/scripts/etc.
 
-Hooks / Stream Events
-~~~~~~~~~~~~~~~~~~~~~
+=== Hooks / Stream Events
 
 * \--change-url parameter passed to hooks
 +
@@ -147,13 +140,11 @@
 set is now included in the stream-events record, making it possible
 for a monitor to easily pull down a patch set and compile it.
 
-Contrib
-~~~~~~~
+=== Contrib
 
 * Example hook to auto-re-approve a trivial rebase
 
-Misc.
-~~~~~
+=== Misc.
 
 * transfer.timeout: Support configurable timeouts for dead clients
 +
@@ -195,11 +186,9 @@
 Apache Commons DBCP to 1.4.
 
 
-Bug Fixes
----------
+== Bug Fixes
 
-Web UI
-~~~~~~
+=== Web UI
 
 * issue 396 Prevent 'no-score' approvals from being recorded
 +
@@ -237,8 +226,7 @@
 'Register New Email...' button.  A cancel button was added to
 close the dialog.
 
-Server Programs
-~~~~~~~~~~~~~~~
+=== Server Programs
 
 * init: Import non-standardly named Git repositories
 +
@@ -265,8 +253,7 @@
 were not properly logged by `gerrit approve` (now gerrit review).
 Fixed by logging the root cause of the failure.
 
-Configuration
-~~~~~~~~~~~~~
+=== Configuration
 
 * Display error when HTTP authentication isn't configured
 +
@@ -282,8 +269,7 @@
 during sign-in.  Administrators can enable following by adding
 `ldap.referral = follow` to their gerrit.config file.
 
-Documentation
-~~~~~~~~~~~~~
+=== Documentation
 
 * documentation: Clarified the ownership of '\-- All Projects \--'
 +
@@ -308,7 +294,6 @@
 the current stable version of the Maven plugin.
 
 
-Version
--------
+== Version
 
 e8fd49f5f7481e2f916cb0d8cfbada79309562b4
diff --git a/ReleaseNotes/ReleaseNotes-2.1.4.txt b/ReleaseNotes/ReleaseNotes-2.1.4.txt
index 3e25163..72eec55 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.4.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.4.txt
@@ -1,23 +1,19 @@
-Release notes for Gerrit 2.1.4
-==============================
+= Release notes for Gerrit 2.1.4
 
 Gerrit 2.1.4 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
-Schema Change
--------------
+== Schema Change
 
 *WARNING* This release contains multiple schema changes.  To upgrade:
 ----
   java -jar gerrit.war init -d site_path
 ----
 
-New Features
-------------
+== New Features
 
-Change Management
-~~~~~~~~~~~~~~~~~
+=== Change Management
 
 * issue 504 Implement full query operators
 +
@@ -51,8 +47,7 @@
 watched project list, and a new menu item was added under the My menu
 to select open changes matching these watched projects.
 
-Web UI
-~~~~~~
+=== Web UI
 
 * issue 579 Remember diff formatting preferences
 +
@@ -82,8 +77,7 @@
 
 * issue 509 Make branch columns link to changes on that branch
 
-Email Notifications
-~~~~~~~~~~~~~~~~~~~
+=== Email Notifications
 
 * issue 311 No longer CC a user by default
 +
@@ -116,8 +110,7 @@
 New fields in the email footer provide additional detail, enabling
 better filtering and classification of messages.
 
-Access Control
-~~~~~~~~~~~~~~
+=== Access Control
 
 * Support regular expressions for ref access rules
 +
@@ -136,8 +129,7 @@
 Groups can now be created over SSH by administrators using the
 `gerrit create-group` command.
 
-Authentication
-~~~~~~~~~~~~~~
+=== Authentication
 
 * Remove password authentication over SSH
 +
@@ -157,8 +149,7 @@
 setting, rather than expiring when the browser closes.  (Previously
 sessions expired when the browser exited.)
 
-Misc.
-~~~~~
+=== Misc.
 
 * Add topic, lastUpdated, sortKey to ChangeAttribute
 +
@@ -184,11 +175,9 @@
 Updated JGit to 0.8.4.89-ge2f5716, log4j to 1.2.16, GWT to 2.0.4,
 sfl4j to 1.6.1, easymock to 3.0, JUnit to 4.8.1.
 
-Bug Fixes
----------
+== Bug Fixes
 
-Web UI
-~~~~~~
+=== Web UI
 
 * issue 352 Confirm branch deletion in web UI
 +
@@ -211,15 +200,13 @@
 Keyboard navigation to standard links like 'Google Accounts'
 wasn't supported.  Fixed.
 
-Misc.
-~~~~~
+=== Misc.
 
 * issue 614 Fix 503 error when Jetty cancels a request
 +
 A bug was introduced in 2.1.3 that caused a server 503 error
 when a fetch/pull/clone or push request timed out.  Fixed.
 
-Version
--------
+== Version
 
 ae59d1bf232bba16d4d03ca924884234c68be0f2
diff --git a/ReleaseNotes/ReleaseNotes-2.1.5.txt b/ReleaseNotes/ReleaseNotes-2.1.5.txt
index 4934223..88288e2 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.5.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.5.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.1.5
-==============================
+= Release notes for Gerrit 2.1.5
 
 Gerrit 2.1.5 is now available:
 
@@ -8,8 +7,7 @@
 This is primarily a bug fix release to 2.1.4, but some additional
 new features were included so its named 2.1.5 rather than 2.1.4.1.
 
-Upgrade Instructions
---------------------
+== Upgrade Instructions
 
 If upgrading from version 2.1.4, simply replace the WAR file in
 `'site_path'/bin/gerrit.war` and restart Gerrit.
@@ -18,11 +16,9 @@
 `java -jar gerrit.war init -d 'site_path'` to upgrade the schema,
 and restart Gerrit.
 
-New Features
-------------
+== New Features
 
-Web UI
-~~~~~~
+=== Web UI
 * issue 361 Enable commenting on commit messages
 +
 The commit message of a change can now be commented on inline, and
@@ -49,8 +45,7 @@
 A 'diffstat' is shown for each file, summarizing the size of the
 change on that file in terms of number of lines added or deleted.
 
-Email Notifications
-~~~~~~~~~~~~~~~~~~~
+=== Email Notifications
 * issue 452 Include a quick summary of the size of a change in email
 +
 After the file listing, a summary totaling the number of files
@@ -58,11 +53,9 @@
 help reviewers to get a quick estimation on the time required for
 them to review the change.
 
-Bug Fixes
----------
+== Bug Fixes
 
-Web UI
-~~~~~~
+=== Web UI
 * issue 639 Fix keyboard shortcuts under Chrome/Safari
 +
 Keyboard shortcuts didn't work properly on modern WebKit browsers
@@ -91,8 +84,7 @@
 is present and will toggle the user's starred flag for that change.
 Fixed.
 
-Access Control
-~~~~~~~~~~~~~~
+=== Access Control
 * issue 672 Fix branch owner adding exclusive ACL
 +
 Branch owners could not add exclusive ACLs within their branch
@@ -118,8 +110,7 @@
 bug which failed to consider the project inheritance if any branch
 (not just the one being uploaded to) denied upload access.
 
-Misc.
-~~~~~
+=== Misc.
 * issue 641 Don't pass null arguments to hooks
 +
 Some hooks crashed inside of the server during invocation because the
@@ -162,12 +153,10 @@
 Gerrit Code Review was only accepting the ';' syntax.  Fixed
 to support both.
 
-Documentation
-~~~~~~~~~~~~~
+=== Documentation
 * Fixed example for gerrit create-account.
 * gerrit.sh: Correct /etc/default path in error message
 
-Version
--------
+== Version
 
 2765ff9e5f821100e9ca671f4d502b5c938457a5
diff --git a/ReleaseNotes/ReleaseNotes-2.1.6.1.txt b/ReleaseNotes/ReleaseNotes-2.1.6.1.txt
index a490c0a..4626c7b 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.6.1.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.6.1.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.6.1
-================================
+= Release notes for Gerrit 2.1.6.1
 
 Gerrit 2.1.6.1 is now available:
 
 link:https://www.gerritcodereview.com/download/gerrit-2.1.6.1.war[https://www.gerritcodereview.com/download/gerrit-2.1.6.1.war]
 
-Schema Change
--------------
+== Schema Change
 
 If upgrading from 2.1.6, there are no schema changes.  Replace the
 WAR and restart the daemon.
@@ -17,8 +15,7 @@
   java -jar gerrit.war init -d site_path
 ----
 
-New Features
-------------
+== New Features
 * Display the originator of each access rule
 +
 The project access panel now shows which project each rule inherits
@@ -37,8 +34,7 @@
 project, provided that the parent project is not the root level
 \-- All Projects \--.
 
-Bug Fixes
----------
+== Bug Fixes
 * Fix disabled intraline difference checkbox
 +
 Intraline difference couldn't be enabled once it was disabled by
diff --git a/ReleaseNotes/ReleaseNotes-2.1.6.txt b/ReleaseNotes/ReleaseNotes-2.1.6.txt
index 520b2a6..83689e7 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.6.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.6.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.6
-==============================
+= Release notes for Gerrit 2.1.6
 
 Gerrit 2.1.6 is now available:
 
 link:https://www.gerritcodereview.com/download/gerrit-2.1.6.war[https://www.gerritcodereview.com/download/gerrit-2.1.6.war]
 
-Schema Change
--------------
+== Schema Change
 
 *WARNING* This release contains multiple schema changes.  To upgrade:
 ----
@@ -14,11 +12,9 @@
 ----
 
 
-New Features
-------------
+== New Features
 
-Web UI
-~~~~~~
+=== Web UI
 * issue 312 Abandoned changes can now be restored.
 * issue 698 Make date and time fields customizable
 * issue 556 Preference to display patch sets in reverse order
@@ -39,8 +35,7 @@
 This is built upon experimental merge code inherited from JGit,
 and is therefore still experimental in Gerrit.
 
-Change Query
-~~~~~~~~~~~~
+=== Change Query
 * issue 688 Match branch, topic, project, ref by regular expressions
 +
 Similar to other features in Gerrit Code Review, starting any of these
@@ -80,8 +75,7 @@
 Gerrit change submission, Gerrit will now send a new "ref-updated"
 event to the event stream.
 
-User Management
-~~~~~~~~~~~~~~~
+=== User Management
 * SSO via client SSL certificates
 +
 A new auth.type of CLIENT_SSL_CERT_LDAP supports authenticating users
@@ -123,8 +117,7 @@
 The internal SSH daemon now supports additional configuration
 settings to reduce the risk of abuse.
 
-Administration
-~~~~~~~~~~~~~~
+=== Administration
 * issue 558 Allow Access rights to be edited by clicking on them.
 
 * New 'Project Owner' system group to define default rights
@@ -186,11 +179,9 @@
 prevent the older (pre-filter-branch) history from being reintroduced
 into the repository.
 
-Bug Fixes
----------
+== Bug Fixes
 
-Web UI
-~~~~~~
+=== Web UI
 * issue 498 Enable Keyboard navigation after change submit
 * issue 691 Make ']' on last file go up to change
 * issue 741 Make ENTER work for 'Create Group'
@@ -224,13 +215,11 @@
 are not project owners may now only view access rights for branches
 they have at least READ +1 permission on.
 
-Change Query
-~~~~~~~~~~~~
+=== Change Query
 * issue 689 Fix age:4days to parse correctly
 * Make branch: operator slightly less ambiguous
 
-Push Support
-~~~~~~~~~~~~
+=== Push Support
 * issue 695 Permit changing only the author of a commit
 +
 Correcting only the author of a change failed to upload the new patch
@@ -257,8 +246,7 @@
 create changes for review were unable to push to a project.  Fixed.
 This (finally) makes Gerrit a replacement for Gitosis or Gitolite.
 
-Replication
-~~~~~~~~~~~
+=== Replication
 * issue 683 Don't assume authGroup = "Registered Users" in replication
 +
 Previously a misconfigured authGroup in replication.config may have
@@ -281,8 +269,7 @@
 
 * issue 658 Allow refspec shortcuts (push = master) for replication
 
-User Management
-~~~~~~~~~~~~~~~
+=== User Management
 * Ensure proper escaping of LDAP group names
 +
 Some special characters may appear in LDAP group names, these must be
@@ -295,8 +282,7 @@
 but cannot because it is already in use by another user on this
 server, the new account won't be created.
 
-Administration
-~~~~~~~~~~~~~~
+=== Administration
 * gerrit.sh: actually verify running processes
 +
 Previously `gerrit.sh check` claimed a server was running if the
@@ -317,6 +303,5 @@
 child project.  Permissions can now be overidden if the category,
 group name and reference name all match.
 
-Version
--------
+== Version
 ef16a1816f293d00c33de9f90470021e2468a709
diff --git a/ReleaseNotes/ReleaseNotes-2.1.7.2.txt b/ReleaseNotes/ReleaseNotes-2.1.7.2.txt
index fdd7725..9c9e6e1 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.7.2.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.7.2.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.7.2
-================================
+= Release notes for Gerrit 2.1.7.2
 
 Gerrit 2.1.7.2 is now available:
 
 link:https://www.gerritcodereview.com/download/gerrit-2.1.7.2.war[https://www.gerritcodereview.com/download/gerrit-2.1.7.2.war]
 
-Bug Fixes
----------
+== Bug Fixes
 * issue 997 Resolve Project Owners when checking access rights
 +
 Members of the 'Project Owners' magical group did not always have
diff --git a/ReleaseNotes/ReleaseNotes-2.1.7.txt b/ReleaseNotes/ReleaseNotes-2.1.7.txt
index 5123279..ad440b5 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.7.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.7.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.7
-==============================
+= Release notes for Gerrit 2.1.7
 
 Gerrit 2.1.7 is now available:
 
 link:https://www.gerritcodereview.com/download/gerrit-2.1.7.war[https://www.gerritcodereview.com/download/gerrit-2.1.7.war]
 
-Schema Change
--------------
+== Schema Change
 *WARNING* This release contains multiple schema changes.  To upgrade:
 ----
   java -jar gerrit.war init -d site_path
@@ -18,8 +16,7 @@
   java -jar gerrit.war ExportReviewNotes -d site_path
 ----
 
-Memory Usage Increase
----------------------
+== Memory Usage Increase
 *WARNING* The JGit delta base cache, whose size is controlled by
 `core.deltaBaseCacheLimit`, has changed in this release from being a
 JVM-wide singleton to per-thread. This alters the memory usage, going
@@ -27,17 +24,14 @@
 change improves performance on big repositories, but may need a larger
 `container.heapLimit` if the number of concurrent operations is high.
 
-New Features
-------------
+== New Features
 
-Change Data
-~~~~~~~~~~~
+=== Change Data
 * issue 64 Create Git notes for submitted changes
 +
 Git notes are automatically added to the `refs/notes/review`.
 
-Query
-~~~~~
+=== Query
 * Search project names by substring
 +
 Entering a word with no operator (for example `gerrit`) will be
@@ -49,8 +43,7 @@
 search for changes whose owner or that has a reviewer in (or not
 in if prefixed with `-`) the specified group.
 
-Web UI
-~~~~~~
+=== Web UI
 * Add reviewer/verifier name beside check/plus/minus
 +
 Change lists (such as from a search result, or in a user's dashboard)
@@ -90,17 +83,14 @@
 SSH public key files by hand.
 
 
-SSH Commands
-~~~~~~~~~~~~
+=== SSH Commands
 * issue 674 Add abandon/restore to `gerrit review`
 * Add `gerrit version` command
 
-Change Upload
-~~~~~~~~~~~~~
+=== Change Upload
 * Display a more verbose "you are not author/committer" message
 
-Documentation
-~~~~~~~~~~~~~
+=== Documentation
 * Detailed error message explanations
 +
 Most common error messages are now described in detail in the
@@ -111,8 +101,7 @@
 * issue 905 Document reverse proxy using Nginx
 * Updated system scaling data in 'System Design'
 
-Outgoing Mail
-~~~~~~~~~~~~~
+=== Outgoing Mail
 * Optionally add Importance and Expiry-Days headers
 +
 New gerrit.config variable `sendemail.importance` can be set to `high`
@@ -122,8 +111,7 @@
 
 * Add support for SMTP AUTH LOGIN
 
-Administration
-~~~~~~~~~~~~~~
+=== Administration
 * Group option to make group visible to all users
 +
 A new group option permits the group to be visible to all users,
@@ -181,8 +169,7 @@
 path used for the authentication cookie, which may be necessary if
 a reverse proxy maps requests to the managed gitweb.
 
-Replication
-~~~~~~~~~~~
+=== Replication
 * Add adminUrl to replication for repository creation
 +
 Replication remotes can be configured with `remote.name.adminUrl` to
@@ -196,8 +183,7 @@
 Replication can now be performed over an authenticated smart HTTP
 transport, in addition to anonymous Git and authenticated SSH.
 
-Misc.
-~~~~~
+=== Misc.
 * Alternative URL for Gerrit's managed Gitweb
 +
 The internal gitweb served from `/gitweb` can now appear to be from a
@@ -210,11 +196,9 @@
 to 1.6, Apache Commons Net to 2.2, Apache Commons Pool to 1.5.5, JGit
 to 0.12.1.53-g5ec4977, MINA SSHD to 0.5.1-r1095809.
 
-Bug Fixes
----------
+== Bug Fixes
 
-Web UI
-~~~~~~
+=== Web UI
 * issue 853 Incorrect side-by-side display of modified lines
 +
 A bug in JGit lead to the side-by-side view displaying wrong and
@@ -261,12 +245,10 @@
 * Always display button text in black
 * Always disable content merge option if user can't change project
 
-commit-msg Hook
-~~~~~~~~~~~~~~~
+=== commit-msg Hook
 * issue 922 Fix commit-msg hook to run on Solaris
 
-Outgoing Mail
-~~~~~~~~~~~~~
+=== Outgoing Mail
 * issue 780 E-mail about failed merge should not use Anonymous Coward
 +
 Some email was sent as Anonymous Coward, even when the user had a
@@ -281,8 +263,7 @@
 * Do not email reviewers adding themselves as reviewers
 * Fix comma/space separation in email templates
 
-Pushing Changes
-~~~~~~~~~~~~~~~
+=== Pushing Changes
 * Avoid huge pushes during refs/for/BRANCH push
 +
 With Gerrit 2.1.6, clients started to push possibly hundreds of
@@ -356,8 +337,7 @@
 no mention if it on the server error log. Now it is reported so the
 site administrator also knows about it.
 
-SSH Commands
-~~~~~~~~~~~~
+=== SSH Commands
 * issue 755 Send new patchset event after its available
 * issue 814 Evict initial members of group created by SSH
 * issue 879 Fix replication of initial empty commit in new project
@@ -365,8 +345,7 @@
 * Automatically create user account(s) as necessary
 * Move SSH command creation off NioProcessor threads
 
-Administration
-~~~~~~~~~~~~~~
+=== Administration
 * Enable git reflog for all newly created projects
 +
 Previously branch updates were not being recorded in the native Git
@@ -388,8 +367,7 @@
 * gerrit.sh: Fix issues on Solaris
 * gerrit.sh: Support spaces in JAVA_HOME
 
-Documentation
-~~~~~~~~~~~~~
+=== Documentation
 * issue 800 documentation: Show example of review -m
 * issue 896 Clarify that $\{name\} is required for replication.
 * Fix spelling mistake in 'Searching Changes' documentation
diff --git a/ReleaseNotes/ReleaseNotes-2.1.8.txt b/ReleaseNotes/ReleaseNotes-2.1.8.txt
index 476e312..e1ed11c 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.8.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.8.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.8
-==============================
+= Release notes for Gerrit 2.1.8
 
 Gerrit 2.1.8 is now available:
 
 link:https://www.gerritcodereview.com/download/gerrit-2.1.8.war[https://www.gerritcodereview.com/download/gerrit-2.1.8.war]
 
-New Features
-------------
+== New Features
 * Add cache for tag advertisements
 +
 When READ level access controls are used on references/branches, this
@@ -39,8 +37,7 @@
 MS-DOS compatibility may have permitted access to special device
 files in any directory, rather than just the "\\.\" device namespace.
 
-Bug Fixes
----------
+== Bug Fixes
 * issue 518 Fix MySQL counter resets
 +
 MySQL databases lost their change_id, account_id counters after
diff --git a/ReleaseNotes/ReleaseNotes-2.1.9.txt b/ReleaseNotes/ReleaseNotes-2.1.9.txt
index 2efc5b6..63bcb20 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.9.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.9.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.1.9
-==============================
+= Release notes for Gerrit 2.1.9
 
 There are no schema changes from link:ReleaseNotes-2.1.8.html[2.1.8].
 
 link:https://www.gerritcodereview.com/download/gerrit-2.1.9.war[https://www.gerritcodereview.com/download/gerrit-2.1.9.war]
 
-Bug Fixes
----------
+== Bug Fixes
 * Patch JGit security hole
 +
 The security hole may permit a modified Git client to gain access
diff --git a/ReleaseNotes/ReleaseNotes-2.1.txt b/ReleaseNotes/ReleaseNotes-2.1.txt
index 127ab09..28cc90d 100644
--- a/ReleaseNotes/ReleaseNotes-2.1.txt
+++ b/ReleaseNotes/ReleaseNotes-2.1.txt
@@ -1,20 +1,17 @@
-Release notes for Gerrit 2.1
-============================
+= Release notes for Gerrit 2.1
 
 Gerrit 2.1 is now available in the usual location:
 
 link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]
 
 
-New site_path Layout
---------------------
+== New site_path Layout
 
 The layout of the `$site_path` directory has been changed in 2.1.
 Configuration files are now stored within the `etc/` subdirectory
 and will be automatically moved there by the init subcommand.
 
-Upgrading From 2.0.x
---------------------
+== Upgrading From 2.0.x
 
   If the server is running a version older than 2.0.24, upgrade the
   database schema to the current schema version of 19.  Download
@@ -37,8 +34,7 @@
 sendemail.smtpPass and ldap.password out of gerrit.config into a
 read-protected secure.config file.
 
-New Daemon Mode
----------------
+== New Daemon Mode
 
 Gerrit 2.1 and later embeds the Jetty servlet container, and
 runs it automatically as part of `java -jar gerrit.war daemon`.
@@ -57,8 +53,7 @@
 link:http://gerrit.googlecode.com/svn/documentation/2.1/index.html[http://gerrit.googlecode.com/svn/documentation/2.1/index.html]
 
 
-New Features
-------------
+== New Features
 
 * issue 19     Link to issue tracker systems from commits
 +
@@ -184,8 +179,7 @@
 +
 Most dependencies were updated to their current stable versions.
 
-Bug Fixes
----------
+== Bug Fixes
 
 * issue 259    Improve search hint to include owner:email
 +
@@ -268,8 +262,7 @@
 `$HOME/.gerritcodereview/tmp`, which should be isolated from
 the host system's /tmp cleaner.
 
-Other=
-------
+== Other=
 
 * Pick up gwtexpui 1.1.4-SNAPSHOT
 * Merge change Ia64286d3
diff --git a/ReleaseNotes/ReleaseNotes-2.10.1.txt b/ReleaseNotes/ReleaseNotes-2.10.1.txt
index 3065492..72d26d1 100644
--- a/ReleaseNotes/ReleaseNotes-2.10.1.txt
+++ b/ReleaseNotes/ReleaseNotes-2.10.1.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.10.1
-===============================
+= Release notes for Gerrit 2.10.1
 
 There are no schema changes from link:ReleaseNotes-2.10.html[2.10].
 
@@ -7,8 +6,7 @@
 link:https://www.gerritcodereview.com/download/gerrit-2.10.1.war[
 https://www.gerritcodereview.com/download/gerrit-2.10.1.war]
 
-Bug Fixes
----------
+== Bug Fixes
 
 * link:https://code.google.com/p/gerrit/issues/detail?id=2260[Issue 2260]:
 LDAP horrendous login time due to recursive lookup.
@@ -19,8 +17,7 @@
 * link:https://code.google.com/p/gerrit/issues/detail?id=3211[Issue 3211]:
 Intermittent Null Pointer Exception when showing process queue.
 
-LDAP
-----
+== LDAP
 
 * Several performance improvements when using LDAP, both in the number of LDAP
 requests and in the amount of data transferred.
@@ -28,13 +25,11 @@
 * Sites using LDAP for authentication but otherwise rely on local Gerrit groups
 should set the new `ldap.fetchMemberOfEagerly` option to `false`.
 
-OAuth
------
+== OAuth
 
 * Expose extension point for generic OAuth providers.
 
-OpenID
-------
+== OpenID
 
 * Add support for Launchpad on the login form.
 
diff --git a/ReleaseNotes/ReleaseNotes-2.10.2.txt b/ReleaseNotes/ReleaseNotes-2.10.2.txt
index ac7c866..49be04e 100644
--- a/ReleaseNotes/ReleaseNotes-2.10.2.txt
+++ b/ReleaseNotes/ReleaseNotes-2.10.2.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.10.2
-===============================
+= Release notes for Gerrit 2.10.2
 
 There are no schema changes from link:ReleaseNotes-2.10.1.html[2.10.1].
 
@@ -7,8 +6,7 @@
 link:https://www.gerritcodereview.com/download/gerrit-2.10.2.war[
 https://www.gerritcodereview.com/download/gerrit-2.10.2.war]
 
-Bug Fixes
----------
+== Bug Fixes
 
 * Work around MyersDiff infinite loop in PatchListLoader. If the MyersDiff diff
 doesn't finish within 5 seconds, interrupt it and fall back to a different diff
@@ -16,15 +14,13 @@
 loop is detected is that the files in the commit will not be compared in-depth,
 which will result in bigger edit regions.
 
-Secondary Index
----------------
+== Secondary Index
 
 * Online reindexing: log the number of done/failed changes in the error_log.
 Administrators can use the logged information to decide whether to activate the
 new index version or not.
 
-Gitweb
-------
+== Gitweb
 
 * Do not return `Forbidden` when clicking on Gitweb breadcrumb. Now when the
 user clicks on the parent folder, redirect to Gerrit projects list screen with
diff --git a/ReleaseNotes/ReleaseNotes-2.10.3.1.txt b/ReleaseNotes/ReleaseNotes-2.10.3.1.txt
index 39312eb..7777bd8 100644
--- a/ReleaseNotes/ReleaseNotes-2.10.3.1.txt
+++ b/ReleaseNotes/ReleaseNotes-2.10.3.1.txt
@@ -1,5 +1,4 @@
-Release notes for Gerrit 2.10.3.1
-=================================
+= Release notes for Gerrit 2.10.3.1
 
 There are no schema changes from link:ReleaseNotes-2.10.3.html[2.10.3].
 
diff --git a/ReleaseNotes/ReleaseNotes-2.10.3.txt b/ReleaseNotes/ReleaseNotes-2.10.3.txt
index f7a69c3..1dd96e7 100644
--- a/ReleaseNotes/ReleaseNotes-2.10.3.txt
+++ b/ReleaseNotes/ReleaseNotes-2.10.3.txt
@@ -1,12 +1,10 @@
-Release notes for Gerrit 2.10.3
-===============================
+= Release notes for Gerrit 2.10.3
 
 Download:
 link:https://www.gerritcodereview.com/download/gerrit-2.10.3.war[
 https://www.gerritcodereview.com/download/gerrit-2.10.3.war]
 
-Important Notes
----------------
+== Important Notes
 
 *WARNING:* There are no schema changes from
 link:ReleaseNotes-2.10.2.html[2.10.2], but Bouncycastle was upgraded to 1.51.
@@ -26,8 +24,7 @@
   java -jar gerrit.war init -d site_path
 ----
 
-New Features
-------------
+== New Features
 
 * Support hybrid OpenID and OAuth2 authentication
 +
@@ -36,15 +33,13 @@
 Particularly, linking of user identities across protocol boundaries and even from
 one OAuth2 identity to another OAuth2 identity wasn't implemented yet.
 
-Configuration
-~~~~~~~~~~~~~
+=== Configuration
 
 * Allow to configure
 link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.10.3/config-gerrit.html#sshd.rekeyBytesLimit[
 SSHD rekey parameters].
 
-SSH
----
+== SSH
 
 * Update SSHD to 0.14.0.
 +
@@ -56,8 +51,7 @@
 * link:https://code.google.com/p/gerrit/issues/detail?id=2797[Issue 2797]:
 Add support for ECDSA based public key authentication.
 
-Bug Fixes
----------
+== Bug Fixes
 
 * Prevent wrong content type for CSS files.
 +
@@ -69,8 +63,7 @@
 * link:https://code.google.com/p/gerrit/issues/detail?id=3289[Issue 3289]:
 Prevent NullPointerException in Gitweb servlet.
 
-Replication plugin
-~~~~~~~~~~~~~~~~~~
+=== Replication plugin
 
 * Set connection timeout to 120 seconds for SSH remote operations.
 +
@@ -78,8 +71,7 @@
 operation. By setting a timeout, we ensure the operation does not get stuck
 forever, essentially blocking all future remote git creation operations.
 
-OAuth extension point
-~~~~~~~~~~~~~~~~~~~~~
+=== OAuth extension point
 
 * Respect servlet context path in URL for login token
 +
@@ -90,34 +82,29 @@
 +
 After web session cache expiration there is no way to re-sign-in into Gerrit.
 
-Daemon
-~~~~~~
+=== Daemon
 
 * Print proper names for tasks in output of `show-queue` command.
 +
 Some tasks were not displayed with the proper name.
 
-Web UI
-~~~~~~
+=== Web UI
 
 * link:http://code.google.com/p/gerrit/issues/detail?id=3044[Issue 3044]:
 Remove