= Release notes for Gerrit 2.13


Gerrit 2.13 is now available:

link:https://www.gerritcodereview.com/download/gerrit-2.13.war[
https://www.gerritcodereview.com/download/gerrit-2.13.war]


== Important Notes

*WARNING:* This release contains schema changes.  To upgrade:
----
  java -jar gerrit.war init -d site_path
----

*WARNING:* To use online reindexing for `changes` secondary index when upgrading
to 2.13.x, the server must first be upgraded to 2.8 (or 2.9) and then through
2.10, 2.11 and 2.12. Skipping a version will prevent online reindexer from
working.

Since 2.13 introduces a new secondary index for accounts, it must be indexed
offline before starting Gerrit:
----
  java -jar gerrit.war reindex --index accounts -d site_path
----
If reindexing will be done offline, you may ignore these warnings and upgrade
directly to 2.13.x using the following command that will reindex both `changes`
and `accounts` secondary indexes:
----
  java -jar gerrit.war reindex -d site_path
----

*WARNING:* The server side hooks functionality is moved to a core plugin. Sites
that make use of server side hooks must install this plugin during site init.


== Release Highlights

* Support for Large File Storage (LFS).

* Metrics interface.

* Hooks plugin.

* Secondary index for accounts.

* File annotations (blame) in side-by-side diff.

== New Features

=== Large File Storage (LFS)

Gerrit provides an
link:https://gerrit-review.googlesource.com/Documentation/dev-plugins.html#lfs-extension[
extension point] that enables development of plugins implementing the
link:https://github.com/github/git-lfs/blob/master/docs/api/v1/http-v1-batch.md[
LFS protocol].

By setting
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/config-gerrit.html#lfs.plugin[
`lfs.plugin`] the administrator can configure the name of the plugin
which handles LFS requests.

=== Access control for git submodule subscriptions

To prevent potential security breaches as described in
link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3311[issue 3311],
it is now only possible for a project to subscribe to a submodule if the
submodule explicitly allows itself to be subscribed.

Please see the
link://https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/user-submodules.html[
submodules user guide] for details.

Note that when upgrading from an earlier version of Gerrit, permissions for
any existing subscriptions will be automatically added during the database
schema migration.

=== Metrics

Metrics about Gerrit's internal state can be sent to external
monitoring systems.

The following metrics are supported:

* HTTP responses
+
TODO details here and in the others

* REST API calls

* SSH sessions

* Caches

* SQL connections

* TODO add more


Plugins can provide implementations of the metrics interface to
report metrics to different monitoring systems. The following
plugins are available:

* link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/metrics-reporter-jmx[
JMX]

* link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/metrics-reporter-graphite[
Graphite]

* link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/metrics-reporter-elasticsearch[
Elasticsearch]


Plugins can also provide metrics.  The following metrics are provided
by the replication plugin:

* Replication latency

* Replication delay

* Replication retry

=== Hooks

Server side hooks are moved to the
link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/hooks[
hooks plugin]. Sites that make use of server side hooks should install this
plugin. After installing the plugin, no additional configuration is needed.
The plugin uses the same configuration settings in `gerrit.config`.

=== Secondary Index

* The secondary index now supports indexing of accounts.
+
The link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/pgm-reindex.html[
reindex program] by default reindexes all changes and accounts. A new
option allows to explicitly specify whether to reindex changes or accounts.
+
The `suggest.fullTextSearch`, `suggest.fullTextSearchMaxMatches` and
`suggest.fullTextSearchRefresh` configuration options are removed. Full text
search is supported by default with the account secondary index.

* New ssh command to
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/cmd-index-changes.html[
reindex changes].


=== UI

* The UI can now be loaded in an iFrame by enabling
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/config-gerrit.html#gerrit.canLoadInIFrame[
gerrit.canLoadInIFrame] in the site configuration.

==== Change Screen

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=106[Issue 106]:
Allow to select merge commit's parent for diff base in change screen.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3035[Issue 3035]:
Allow to remove specific votes from a change, while leaving the reviewer on the
change.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3487[Issue 3487]:
Use 'Ctrl-Alt-e' instead of 'e' to open edit mode.

==== Diff Screens

* Add all syntax highlighting available in CodeMirror.

* Improve search experience in diff screen
+
Ctrl-F, Ctrl-G and Shift-Ctrl-G now bind to the search dialog box provided by
CodeMirror's search add-on. Enter and Shift-Enter navigate among the search
results from the CodeMirror search, just like they do in a normal browser
search. Esc now clears the search result.
+
If the user sets `Render` to `Slow` in the diff preferences and the file is less
than 4000 lines (huge), then Ctrl-F, Ctrl-G and Shift-Ctrl-G fall back to the
browser search.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=2968[Issue 2968]:
Allow to go back to change list by keyboard shortcut from diff screens.

==== Side-By-Side Diff Screen

* Blame annotations
+
By enabling
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/config-gerrit.html#change.allowBlame[
`change.allowBlame`], blame annotations can be shown in the side-by-side diff
screen gutter. Clicking the annotation opens the relevant change.

==== User Preferences

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=989[Issue 989]:
New option to control email notifications.
+
Users can now choose between 'Enabled', 'Disabled' and 'CC Me on Comments I Write'.

* New option to control adding 'Signed-off-by' footer in commit message of new changes
created online.

* New option to control auto-indent width in inline editor.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=890[Issue 890]:
New diff option to control whether to skip unchanged files when navigating to
the previous or the next file.

=== Changes

In order to avoid potentially confusing behavior, when submitting changes in a
batch, submit type rules may not be used to mix submit types on a single branch,
and trying to submit such a batch will fail.

=== REST API

==== Accounts

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3766[Issue 3766]:
Allow users with the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/access-control.html#capability_modifyAccount[
'ModifyAccount' capability] to get the preferences for other users via the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-accounts.html#get-user-preferences[
Get User Preferences] endpoint.

* Rename 'Suggest Account' to
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-accounts.html#query-account[
'Query Account'] and add support for arbitrary account queries.
+
The `_more_accounts` flag is set on the last result when there are more results
than the limit. The `DETAILS` and `ALL_EMAILS` options may be set to control
whether the results should include details (full name, email, username, avatars)
and all emails, respectively.

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-accounts.html#get-watched-projects[
Get Watched Projects].

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-accounts.html#set-watched-projects[
Set Watched Projects].

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-accounts.html#delete-watched-projects[
Delete Watched Projects].

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-accounts.html#get-stars[
Get Star Labels from Change].

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-accounts.html#set-stars[
Update Star Labels on Change].

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-accounts.html#get-oauth-token[
Get OAuth Access Token].

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-accounts.html#list-contributor-agreements[
List Contributor Agreements].

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-accounts.html#sign-contributor-agreement[
Sign Contributor Agreement].

==== Changes

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3579[Issue 3579]:
Append submitted info to ChangeInfo.

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-changes.html#move-change[
Move Change].

==== Groups

* Add `-s` as an alias for `--suggest` on the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-groups.html#suggest-group[
Suggest Group] endpoint.

==== Projects

* Add `async` option to the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-projects.html#run-gc[
Run GC] endpoint to allow garbage collection to run asynchronously.

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-projects.html#get-access[
List Access Rights].

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-projects.html#set-access[
Add, Update and Delete Access Rights].

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-projects.html#create-tag[
Create Tag].

* New endpoint:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/rest-api-projects.html#get-mergeable-info[
Get Mergeable Information].

=== Plugins

* Secure settings
+
Plugins may now store secure settings in `etc/$PLUGIN.secure.config` where they
will be decoded by the Secure Store implementation.

* Exported dependencies
+
Gson is now an exported dependency. Plugin no longer need to explicitly add
a dependency on it.

=== Misc

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=4015[Issue 4015]:
Allow setting a comment message when uploading a change.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3220[Issue 3220]:
Append approval info to every comment-added stream event and hook.

* The `administrateServer` capability can be assigned to groups by setting
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.13/config-gerrit.html#capability.administrateServer[
capability.administrateServer] in the site configuration.
+
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.

== Bug Fixes

* Don't add the same SSH key multiple times.
+
If an already existing SSH key was added, a duplicate entry was added to the
list of user's SSH keys.

* Respect the 'Require a valid contributor agreement to upload' setting
when creating changes via the UI.
+
If a user had not signed a CLA, it was still possible for them to create a new
change with the 'Revert' or 'Cherry Pick' button.

* Make Lucene index more stable when being interrupted.

* Don't show the `start` and `idle` columns in the `show-connections`
output when the ssh backend is NIO2.
+
The NIO2 backend doesn't provide the start and idle times, and the
values being displayed were just dummy values. Now these values are
only displayed for the MINA backend.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=4150[Issue 4150]:
Deleting a draft inline comment no longer causes the change's `Updated` field to
be bumped.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=4099[Issue 4099]:
Fix SubmitWholeTopic does not update subscriptions.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3603[Issue 3603]:
Fix editing a submodule via inline edit.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=4069[Issue 4069]:
Fix highlights in scrollbar overview ruler not moved when extending the
displayed area.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3446[Issue 3446]:
Respect the `Skip Deleted` diff preference.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3445[Issue 3445]:
Respect the `Skip Uncommented` diff preference.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=4051[Issue 4051]:
Fix empty `From` email header.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3423[Issue 3423]:
Fix intraline diff for added spaces.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=1867[Issue 1867]:
Remove `no changes made` error case when the only difference between a new
commit and the previous patch set of the change is the committer.

Remove "no changes made" error case
* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3831[Issue 3831]:
Prevent creating groups with the same name as a system group.

* link:https://bugs.chromium.org/p/gerrit/issues/detail?id=3754[Issue 3754]:
Fix `View All Accounts` permission to allow accounts rest endpoint to access
email info.

== Dependency updates

* Add dependency on blame-cache 0.1-9

* Add dependency on guava-retrying 2.0.0

* Add dependency on jsr305 3.0.1

* Add dependency on metrics-core 3.1.2

* Upgrade auto-value to 1.3-rc1

* Upgrade commons-net to 3.5

* Upgrade CodeMirror to 5.17.0

* Upgrade Guava to 19.0

* Upgrade Gson to 2.7

* Upgrade Guice to 4.1.0

* Upgrade gwtjsonrpc to 1.8

* Upgrade gwtorm to 1.15

* Upgrade javassist to 3.20.0-GA

* Upgrade Jetty to 9.2.14.v20151106

* Upgrade JGit to 4.4.1.201607150455-r.137-gdd2a5a7

* Upgrade joda-convert to 1.8.1

* Upgrade joda-time to 2.9.4

* Upgrade Lucene to 5.5.0

* Upgrade mina to 2.0.10

* Upgrade sshd-core to 1.2.0