Release notes for Gerrit 2.9
============================


Gerrit 2.9 is now available:

link:https://gerrit-releases.storage.googleapis.com/gerrit-2.9.war[
https://gerrit-releases.storage.googleapis.com/gerrit-2.9.war]

*WARNING:* Support for Java 1.6 has been discontinued.
As of Gerrit 2.9, Java 1.7 is required.

Gerrit 2.9 includes the bug fixes done with
link:ReleaseNotes-2.8.1.html[Gerrit 2.8.1],
link:ReleaseNotes-2.8.2.html[Gerrit 2.8.2],
link:ReleaseNotes-2.8.3.html[Gerrit 2.8.3],
link:ReleaseNotes-2.8.4.html[Gerrit 2.8.4],
link:ReleaseNotes-2.8.5.html[Gerrit 2.8.5],
link:ReleaseNotes-2.8.6.html[Gerrit 2.8.6] and
link:ReleaseNotes-2.8.6.1.html[Gerrit 2.8.6.1].
These bug fixes are *not* listed in these release notes.

Important Notes
---------------


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

*WARNING:* Support for query via the SQL index is removed. The usage of
a secondary index is now mandatory.

*WARNING:* The new change screen only displays download commands if the
`download-commands` core plugin or any other plugin providing download
commands is installed. The `download-commands` plugin provides the
standard download schemes and commands. It is packaged together with
Gerrit and can be installed, or upgraded, during the
link:https://gerrit-review.googlesource.com/Documentation/pgm-init.html[
site initialization]:

.Installing the plugin for the first time
- Batch init:
+
By default the batch init does *not* install any core plugin. To
install the `download-commands` plugin during batch init, specify the
'--install-plugin download-commands' option:
+
----
  $ java -jar gerrit-2.9.war init -d site --batch --install-plugin download-commands
----

- Interactive init:
+
There is a question whether the `download-commands` plugin should be
installed. To install the plugin the question must be answered with `y`:
+
----
  Install plugin download-commands version v2.9 [y/N]? y
----

.Upgrading the plugin
Pay attention that the `download-commands` plugin from Gerrit 2.8 is
*not* compatible with Gerrit 2.9 and must be upgraded:

- Batch init:
+
With the batch init it is *not* possible to upgrade core plugins.

- Interactive init:
+
The interactive init asks whether the plugin should be upgraded:
+
----
  Install plugin download-commands version v2.9 [y/N]? y
  version v2.8.6.1 is already installed, overwrite it [y/N]? y
----

- Manual upgrade:
+
The plugin can be upgraded manually by copying the new plugin jar into
the site's `plugins` folder.

*WARNING:* Upgrading to 2.9.x requires the server be first upgraded to 2.1.7 (or
a later 2.1.x version), and then to 2.9.x.  If you are upgrading from 2.2.x.x or
later, you may ignore this warning and upgrade directly to 2.9.x.


Release Highlights
------------------


* link:http://code.google.com/p/gerrit/issues/detail?id=2065[Issue 2065]:
The new change screen is now the default change screen.
+
The
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/user-review-ui.html[
documentation of the new review UI] describes the new screens in detail
and highlights the important functionality with screenshots.
+
Users that are accessing the new change screen for the first time are
informed about the new change screen by a welcome popup. The welcome
popup links to the review UI documentation and allows users to go back
to the old change screen.


New Features
------------


Web UI
~~~~~~


Global
^^^^^^

* Project links by default link to the project dashboard.


New Change Screen
^^^^^^^^^^^^^^^^^


* The new change screen is now the default change screen.

* The layout was changed so that the focus is now on the commit
message, the change ID and the change status.

* Draft comments are displayed in the reply box.
+
There are links to navigate to the inline comments which can be used if
a comment needs to be edited.

* New inline comments from other users, that were published after the
current user last reviewed this change, are highlighted in bold.

* New summary comments from other users, that were published after the
current user last reviewed this change, are automatically expanded in
the change history.
+
The support for the old comment visibility strategy is discontinued.

* link:http://code.google.com/p/gerrit/issues/detail?id=93[Issue 93]:
Inline comments are shown in the change history.

* link:http://code.google.com/p/gerrit/issues/detail?id=592[Issue 592]:
A reply icon is shown on each change message.

* Quoting is possible when replying to a comment.

* link:http://code.google.com/p/gerrit/issues/detail?id=2313[Issue 2313]:
Show whether a related change is merged or old.

* New link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/user-review-ui.html#related-changes[
Related Changes] tabs:
** `Cherry-Picks`
** `Same Topic`
** `Conflicts With`

* The title of the `Patch Sets` drop-down panel shows the number of the
currently viewed patch set and the total number of patch sets, in the
form: "current patch set/number of patch sets".

* The currently viewed patch set is displayed in the `Patch Sets` title.

* Keyboard shortcuts to navigate to next/previous patch set.

* Support `[`, `/` and `]` keys to navigate between files in a cycle.

* link:http://code.google.com/p/gerrit/issues/detail?id=2078[Issue 2078]:
Show a tooltip on reviewers indicating on which labels they can vote.

* The `Submit` button is enabled even if the change is not mergeable.
+
This allows to do the conflict resolution for a change series in a
single merge commit and submit the changes in reverse order.

* New `Open All` button in files header.

* If a merge commit is viewed this is highlighted by an icon. In this
case the parent commits are also shown.

* link:http://code.google.com/p/gerrit/issues/detail?id=2191[Issue 2191]:
New copy-to-clipboard button for commit ID.


New Side-by-Side Diff Screen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* link:http://code.google.com/p/gerrit/issues/detail?id=348[Issue 348]:
The lines of a patch file are linkable.
+
These links can be used to directly link to certain inline comments.

* link:http://code.google.com/p/gerrit/issues/detail?id=2395[Issue 2395]:
The line length preference is used to draw a margin line at that many
columns of text.
+
This allows a user to configure their preferred width (e.g. 80 columns
or 100 columns) and see the margin, making it easier to identify lines
that run over that width.

* link:http://code.google.com/p/gerrit/issues/detail?id=2530[Issue 2530]:
All diff preferences are honored.

* link:http://code.google.com/p/gerrit/issues/detail?id=148[Issue 148]:
The full file path is shown.


Change List / Dashboards
^^^^^^^^^^^^^^^^^^^^^^^^

* The `Status` column shows `Merge Conflict` for changes that are not
mergeable.

* A new `Size` column shows the change size as a colored bar.
** The user preference `Show Change Sizes As Colored Bars In Changes Table`
can be disabled to get the size information displayed as text.
** The number of changed lines by which a change is considered as a
large change can be
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/config-gerrit.html#change.largeChange[
configured].

* Support to drill down into dashboard section.
+
Clicking on the section title executes the query of this section
without the `limit` operator.


Project Screens
^^^^^^^^^^^^^^^

* The general project screen provides a copyable clone command that
automatically installs the `commit-msg` hook.

* link:http://code.google.com/p/gerrit/issues/detail?id=562[Issue 562]:
Project owners can change `HEAD` from the project branches screen.

* link:http://code.google.com/p/gerrit/issues/detail?id=1298[Issue 1298]:
Administrators can change the parent project from the project access
screen; other users can save changes to the parent project for review
and get the change approved by an administrator.

* The project list displays icons for projects that are read only or
hidden.

* The Git garbage collection can be triggered from the general project
screen if the user has the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/access-control.html#capability_runGC[
Run Garbage Collection] global capability.


User Preferences
^^^^^^^^^^^^^^^^

* Users can choose the UK date format to render dates and timestamps in
the UI.


Secondary Index
~~~~~~~~~~~~~~~

* Support for query via the SQL index is removed. The usage of
a secondary index is now mandatory.

* New `--recheck-mergeable` option on the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/pgm-reindex.html[
reindex] program.

ssh
~~~

* New `--notify` option on the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/cmd-review.html[
review] command allowing to control when email notifications should be
sent.

* link:http://code.google.com/p/gerrit/issues/detail?id=1752[Issue 1752]:
New `--branch` option on the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/cmd-review.html[
review] command.

* New `--all-reviewers` option on the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/cmd-query.html[
query] command allowing query results to include information about all
reviewers added on the change.

* New link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/cmd-apropos.html[
apropos] command to search the Gerrit documentation.

* link:http://code.google.com/p/gerrit/issues/detail?id=1156[Issue 1156]:
New link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/cmd-create-branch.html[
create-branch] command.

REST API
~~~~~~~~


Projects
^^^^^^^^


* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/rest-api-projects.html#get-content[
Get content of a file from HEAD of a branch].

Documentation
^^^^^^^^^^^^^


* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/rest-api-documentation.html#search-documentation.html[
Search documentation].

Access Rights
~~~~~~~~~~~~~


* New link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/access-control.html#capability_viewAllAccounts[
global capability for viewing all accounts].

* New link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/access-control.html#capability_viewPlugins[
global capability for viewing the list of installed plugins].

* link:http://code.google.com/p/gerrit/issues/detail?id=1993[Issue 1993]:
New `Change Owner` group that allows to assign label permissions to the change owner.

* Support link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/access-control.html#category_submit_on_behalf_of[
on behalf of for submit].

* Allow service users to access REST API if `auth.gitBasicAuth = true`.
+
If link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/config-gerrit.html#auth.gitBasicAuth[
auth.gitBasicAuth] is set to `true` in the `gerrit.config` file all
HTTP traffic is authenticated using standard `BasicAuth` and the
credentials are validated using the same auth method as configured for
the Gerrit Web UI. E.g. for LDAP this means that users must use their
LDAP password for Git over HTTP and for accessing the REST API.
+
Service users are technical users that were created by the
`create-account` SSH command. These users only exist in Gerrit and
hence they do not have any LDAP password. This is why service users
were not able to make use of the REST API if `auth.gitBasicAuth` was
set to `true`.
+
Now if `auth.gitBasicAuth` is set to `true` users that exist only in
Gerrit but not in LDAP are authenticated with their HTTP password from
the Gerrit database.

Search
~~~~~~

* New link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/user-search.html#mergeable[
is:mergeable] search operator.
+
Finds changes that have no merge conflicts and can be merged into the
destination branch.

* link:http://code.google.com/p/gerrit/issues/detail?id=2163[Issue 2163]:
New link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/user-search.html#parentproject[
parentproject] search operator.
+
Finds changes in the specified project or in one of its child projects.

* link:http://code.google.com/p/gerrit/issues/detail?id=2162[Issue 2162]:
New link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/user-search.html#conflicts[
conflicts] search operator.
+
Finds changes that conflict with the specified change.

* New operators for absolute last-updated-on search.
** link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/user-search.html#before_until[
before / until]
** link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/user-search.html#after_since[
after / since]

* Support exact match on file parts in
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/user-search.html#file[
file] operator.

* Query shortcuts
** `o` = `owner`
** `r` = `reviewer`
** `p` = `project`
** `f` = `file`

Daemon
~~~~~~


* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/dev-inspector.html[
Gerrit Inspector]: interactive Jython shell.
+
New `-s` option is added to the Daemon to start an interactive Jython shell for inspection and
troubleshooting of live data of the Gerrit instance.

Documentation
~~~~~~~~~~~~~


* The documentation is now
https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/rest-api-documentation.html#search-documentation.html[
searchable]:
+
On each documentation page there is search box in the right top corner
that allows to search in the documentation.

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/user-review-ui.html[
Documentation of the new review UI].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/intro-project-owner.html[
New Project Owner Guide].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/index.html[
Newly structured documentation index].


Configuration
~~~~~~~~~~~~~

* New init step for installing the `Verified` label.

* link:http://code.google.com/p/gerrit/issues/detail?id=2257[Issue 2257]:
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/config-gerrit.html#repository.name.defaultSubmitType[
Default submit type] for newly created projects can be configured.

* `sshd_log` and `httpd_log` can use log4j configuration.

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/config-gerrit.html#change.allowDrafts[
Draft workflow can be disabled].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/config-project-config.html#receive.checkReceivedObjects[
Project configuration for checking of received objects].

* link:http://code.google.com/p/gerrit/issues/detail?id=2318[Issue 2318]:
Allow the text of the "Report Bug" link to be configured.


Misc
~~~~

* The removal of reviewers and their votes is recorded as a change
message.

* link:http://code.google.com/p/gerrit/issues/detail?id=2229[Issue 2229]:
The change URL is returned on push if the change is updated.

* The topic is included into merge commit messages if all merged
changes have the same topic.

* Stable CSS class names.


Plugins
~~~~~~~


* Plugin API to invoke the REST API.

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/dev-plugins.html#screen[
Plugins can add entire screens to Gerrit].

* Plugins can have a
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/dev-plugins.html#settings-screen[
settings screen] which is linked from plugin list screen.

* Support to edit
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/dev-plugins.html#simple-project-specific-configuration[
project plugin configuration parameters] in the UI.

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/config-gerrit.html#plugins.allowRemoteAdmin[
Remote plugin administration is by default disabled].


Extension Points
^^^^^^^^^^^^^^^^


* Extension point to provide a "Message Of The Day".

* Validation for
** link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/config-validation.html#new-project-validation[
project creation].
** link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/config-validation.html#new-group-validation[
group creation].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/dev-plugins.html#init_step[
Init steps can do initialization after the site is created].
** The `All-Projects` `project.config` can be read and edited

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/dev-plugins.html#receive-pack[
Initialization of ReceivePack].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/dev-plugins.html#post-receive-hook[
Registration of PostReceiveHooks].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/dev-plugins.html#root-level-commands[
Registration of root level commands].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/dev-plugins.html#multiple-commands[
Multiple SSH commands can be bound to the same class].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/config-gerrit.html#database.dataSourceInterceptorClass[
DataSource Interception].


JavaScript Plugins
^^^^^^^^^^^^^^^^^^


* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.9/js-api.html#self_on[
JavaScript Callbacks]
** Gerrit.on(\'history\', f)
** Gerrit.on(\'submitchange\', f)
** Gerrit.on(\'showchange\', f)

* `change_plugins` element on the new change screen that allows to
insert arbitrary HTML fragments from plugins.


Bug Fixes
---------


Access Rights
~~~~~~~~~~~~~


* Fix possibility to overcome BLOCK permissions.


Web UI
~~~~~~


* link:http://code.google.com/p/gerrit/issues/detail?id=2652[Issue 2652]:
Copy label approvals when cherry-picking change to same branch.

* link:http://code.google.com/p/gerrit/issues/detail?id=2662[Issue 2662]:
Limit file list in new change screen to files that were touched in new
patch set.

* link:http://code.google.com/p/gerrit/issues/detail?id=2308[Issue 2308]:
Show related changes in new change screen for merged changes if there
are open descendants.

* link:http://code.google.com/p/gerrit/issues/detail?id=2635[Issue 2635]:
Fix copying of download commands by 'Cmd-C' in Safari.

* link:http://code.google.com/p/gerrit/issues/detail?id=2178[Issue 2178]:
Fix background of reply box on new change screen getting transparent.

* link:http://code.google.com/p/gerrit/issues/detail?id=2362[Issue 2362]:
Show quick approve button only for current patch set.

* link:http://code.google.com/p/gerrit/issues/detail?id=2405[Issue 2405]:
Update `Patch Sets` drop-down panel when draft patch set is deleted.

* link:http://code.google.com/p/gerrit/issues/detail?id=2397[Issue 2397]:
Fix linkifying of topics that are set to a URL.

* link:http://code.google.com/p/gerrit/issues/detail?id=2151[Issue 2151]:
Fix overflowing of long lines in commit message block.

* link:http://code.google.com/p/gerrit/issues/detail?id=2401[Issue 2401]:
Fix truncated long lines in new side-by-side diff screen.

* link:http://code.google.com/p/gerrit/issues/detail?id=2225[Issue 2225]:
Display larger icons for Prev / Next and Up to Change links on new
side-by-side diff screen.

* link:http://code.google.com/p/gerrit/issues/detail?id=2340[Issue 2340]:
Fix selection in new side-by-side diff screen.

* link:http://code.google.com/p/gerrit/issues/detail?id=2409[Issue 2409]:
Show in new side-by-side diff screen updates of submodule links.

* link:http://code.google.com/p/gerrit/issues/detail?id=2481[Issue 2481]:
After showing a binary file in the unified diff screen switch back to
the side-by-side diff screen when the user navigates to the
next/previous file.

* link:http://code.google.com/p/gerrit/issues/detail?id=2417[Issue 2417]:
Respect base diff revision for files REST call.

* link:http://code.google.com/p/gerrit/issues/detail?id=2654[Issue 2654]:
Require the user to confirm setting the username.
+
Once the username has been set, it cannot be edited. This can cause
problems for users who accidentally set the wrong username. A
confirmation dialog now warns the user that setting the username is
permanent and the username is only set when the user confirms.

* link:https://code.google.com/p/gerrit/issues/detail?id=2635[Issue 2635]:
Fix copying from copyable label in Safari.


Secondary Index
~~~~~~~~~~~~~~~

* Fix Online Reindexing.

* Fix for full-text search with Lucene.
+
The full-text search was using a fuzzy query which used the edit
distance to find terms in the index close to the provided search term.
This produced bizarre results for queries like "message:1234".
+
Instead, use Lucene's QueryBuilder with an analyzer to convert a
full-text search word/phrase into a phrase query.

* link:http://code.google.com/p/gerrit/issues/detail?id=2281[Issue 2281]:
Reindex change after updating commit message.


REST
~~~~


* link:http://code.google.com/p/gerrit/issues/detail?id=2568[Issue 2568]:
Update description file during `PUT /projects/{name}/config`.


SSH
~~~


* link:http://code.google.com/p/gerrit/issues/detail?id=2516[Issue 2516]:
Fix parsing of label name on `review` command.

* link:http://code.google.com/p/gerrit/issues/detail?id=2440[Issue 2440]:
Clarify for review command when `--verified` can be used.


Plugins
~~~~~~~


* link:http://code.google.com/p/gerrit/issues/detail?id=2551[Issue 2551]:
Handle absolute URLs in the top level menu.

* link:http://code.google.com/p/gerrit/issues/detail?id=2391[Issue 2391]:
Respect servlet context path in URL for top menu items.


Other
~~~~~


* link:http://code.google.com/p/gerrit/issues/detail?id=2382[Issue 2382]:
Clean left over data migration after removal of TrackingIds table.


Upgrades
--------

* Update JGit to 3.4.0.201405051725-m7
+
This upgrade fixes the MissingObjectExceptions in Gerrit that are
described in link:http://code.google.com/p/gerrit/issues/detail?id=2025[
issue 2025].

* Update gwtjsonrpc to 1.5
* Update gwtorm to 1.13
* Update guava to 16.0

* Update H2 to 1.3.174
+
This version includes a fix for an LOB deadlock between reading and
updating LOB columns. This could lead to a deadlock between web and SSH
clients as described in
link:http://code.google.com/p/gerrit/issues/detail?id=2365[issue 2365].

* Update Jetty to 9.1.0.v20131115
* Update Servlet API to 3.1
* Update Lucene to 4.6.0
* Update GWT to 2.6.0


Plugins
-------

Replication
~~~~~~~~~~~

* Default push refSpec is changed to `refs/*:refs/*` (non-forced push).
+
The default push refSpec for the replication plugin has changed from `forced`
to `non-forced` push (was `+refs/*:refs/*` and now is `refs/*:refs/*`). This change
should not impact typical replication topologies where the slaves are read-only
and can be pushed by their masters only. If you wanted explicitly to overwrite
all changes on the slaves, you need to add a `push=+refs/*:refs/*` configuration
entry for each replication target.

* Support replication of HEAD updates.

* Stream events for ref replication.

* Replications failed due to "failed to lock" errors are retried.

* Configuration changes can be detected and replication is
automatically restarted.

Issue Tracker System plugins
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*WARNING:* The `hooks-*` plugins (`plugins/hooks-bugzilla`,
`plugins/hooks-jira` and `plugins/hooks-rtc`) are deprecated with
Gerrit 2.9.

There are new plugins for the integration with Bugzilla, Jira and IBM
Rational Team Concert:

* link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/its-bugzilla[plugins/its-bugzilla]
* link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/its-jira[plugins/its-jira]
* link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/its-rtc[plugins/its-rtc]

The new issue tracker system plugins have a common base which is
link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/its-base[plugins/its-base].

The configuration of the new plugins is slightly different than the
configuration of the old plugins because they use different section
names in the Gerrit configuration. For easy migration the new plugins
have an init step that allows to take over the configuration from the
old plugins during the Gerrit initialization phase.

New Features:

* The issue tracker integration can be enabled/disabled per project.
* Parent projects can enforce the issue tracker integration for their
  child projects.
* It can be configured for which branches of a project the issue
  tracker integration is enabled.
* Whether the issue tracker integration is enabled/disabled for a
  project can be changed from the ProjectInfoScreen in the Gerrit
  WebUI.