Release notes for Gerrit 2.8
============================


Gerrit 2.8 is now available:

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


Schema Change
-------------


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

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

*WARNING:* The replication plugin now automatically creates missing repositories
on the destination if during the replication of a ref the target repository is
found to be missing. This is a change in behavior of the replication plugin. To go
back to the old behavior, set the parameter `remote.NAME.createMissingRepositories`
in the `replication.config` file to `false`.


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


* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/intro-change-screen.html[
New change screen] with completely redesigned UI and fully using the REST API.

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-gerrit.html#index[
Secondary indexing with Lucene and Solr].

* Lots of new link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api.html[
REST API endpoints].

* New
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/dev-plugins.html#ui_extension[
UI extension] and
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/js-api.html[
JavaScript API] for plugins.

* New build system using Facebook's link:http://facebook.github.io/buck/[Buck].

* New core plugin: Download Commands.


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

Build
~~~~~

* Gerrit is now built with
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/dev-buck.html[
Buck].

* Documentation is now built with Buck and link:http://asciidoctor.org[Asciidoctor].


Indexing and Search
~~~~~~~~~~~~~~~~~~~

Gerrit can be configured to use a
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-gerrit.html#index[
secondary index] with Lucene or Solr.

Existing search operations use the secondary index, when enabled, to increase
performance and reduce resource usage.

The following additional search operations are possible when secondary indexing
is enabled:

* New
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/user-search.html#comment[
`comment` search operator].

* The link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/user-search.html#file[
`file` operator] can be used to find changes on the specified file.

* Regular expressions are allowed in `file` searches.


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

* Project owners can define `receive.maxObjectSizeLimit` in the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-gerrit.html#receive.maxObjectSizeLimit[
project configuration] to further reduce the global setting.

* Site administrators can define a
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-mail.html#_footer_vm[
footer template] that will be appended to the end of all outgoing emails after
the 'ChangeFooter' and 'CommentFooter'.

* New `topic-changed` hook and stream event is fired when a change's topic is
edited from the Web UI or via a REST API.

* New options `--list-plugins` and `--install-plugins` on the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/pgm-init.html[
site initialization command].

* New `auth.httpDisplaynameHeader` and `auth.httpEmailHeader` in the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-gerrit.html#__a_id_auth_a_section_auth[
authentication configuration].
+
When using HTTP-based authentication, the SSO can be delegated to check not only
the user credentials but also to fetch the full user-profile.
+
With the config properties `auth.httpDisplaynameHeader` and `auth.httpEmailHeader`
it is possible to configure the name of the headers used for propagating this extra
information and enforce them on the user profile during login and beyond.

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-gerrit.html#__a_id_httpd_a_section_httpd[
Customizable registration page for HTTP authentication].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-gerrit.html#__a_id_httpd_a_section_httpd[
Configurable external `robots.txt` file].

* Support for
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/database-setup.html#createdb_oracle[
Oracle database].

* New bash completion script for autocompletion of parameters to the gerrit.sh wrapper.

* The site can be
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-auto-site-initialization.html[
auto-initialized on server startup].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-gerrit.html#httpd.filterClass[
Configurable filtering of HTTP traffic through Gerrit's HTTP protocol].

* Labels can be
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-labels.html#httpd.label_copyAllScoresIfNoCodeChange[
configured to copy scores forward to new patch sets if there is no code change].

* Labels can be
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-labels.html#httpd.label_copyAllScoresOnTrivialRebase[
configured to copy scores forward to new patch sets for trivial rebases].

Web UI
~~~~~~


Global
^^^^^^

* The change status is shown in a separate column on dashboards and search results.

Change Screens
^^^^^^^^^^^^^^


* New change screen with completely redesigned UI, using the REST API.
+
Site administrators can
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-gerrit.html#gerrit.changeScreen[
configure which change screen is shown by default].
+
Users can choose which one to use in their personal preferences, either using
the site default or explicitly choosing the old one or new one.

* link:https://code.google.com/p/gerrit/issues/detail?id=141[Issue 141]:
In the new change screen, comments can be added on a range of lines.

* New button to cherry-pick the change to another branch.

* When issuing a rebase via the Web UI, the committer is now the logged in
  user, rather than "Gerrit Code Review".
+
If the user has more than one email address, the preferred email address will
be used.

* Default user's full name to git committer name if user has not configured a
full name in their profile.

* Include comment author attributes in comment panels.
+
Comment author's email address and name are included as attributes in comment
panels.  This makes it easier to filter out CI-based comments using user
scripts.

* Copy reviewed flag to new patch sets for identical files.
+
If a user has already seen and reviewed a file, the 'reviewed' flag is forwarded
on to the next patch set when the content of the file in the next patch set is
identical to the reviewed file.

* "Uploaded Patch Set 1" change message is added on changes when they
are uploaded.


REST API
~~~~~~~~

* Several new link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api.html[
REST API endpoints] are added.

* REST views can determine how long their response should be cached.

* REST views can handle 'HTTP 422 Unprocessable Entity' responses.

Access Rights
^^^^^^^^^^^^^


* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-access.html#list-access[
List access rights for project(s)]

Accounts
^^^^^^^^


* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#create-account[
Create account]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#get-account-name[
Get account full name]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#set-account-name[
Set account full name]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#delete-account-name[
Delete account full name]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#list-account-emails[
List account email addresses]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#get-account-email[
Get account email address]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#set-preferred-email[
Set account preferred email address]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#create-account-email[
Create account email]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#delete-account-email[
Delete account email]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#get-active[
Get account state]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#set-active[
Set account state to active]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#delete-active[
Set account state to inactive]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#get-http-password[
Get account HTTP password]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#set-http-password[
Set or generate account HTTP password]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#delete-http-password[
Delete account HTTP password]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#list-ssh-keys[
List account SSH keys]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#get-ssh-key[
Get account SSH key]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#add-ssh-key[
Add account SSH key]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#delete-ssh-key[
Delete account SSH key]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#get-username[
Get account username]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#get-starred-changes[
Get starred changes]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#star-change[
Star change]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-accounts.html#unstar-change[
Unstar change]

Changes
^^^^^^^


* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-changes.html#rebase-change[
Rebase change]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-changes.html#cherry-pick[
Cherry-pick revision]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-changes.html#get-content[
Get content of a file in a revision]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-changes.html#get-patch[
Get revision as a formatted patch]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-changes.html#get-diff[
Get diff of a file in a revision]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-changes.html#get-commit[
Get parsed commit of a revision]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-changes.html#publish-draft-change[
Publish draft change]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-changes.html#delete-draft-change[
Delete draft change]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-changes.html#suggest-reviewers[
Suggest reviewers]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-changes.html#get-included-in[
Get included in]


Config
^^^^^^

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-config.html#get-capabilities[
Get capabilities]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-config.html#get-version[
Get version] (of the Gerrit server)


Projects
^^^^^^^^


* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-projects.html#list-branches[
List branches]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-projects.html#get-branch[
Get branch]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-projects.html#create-branch[
Create branch]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-projects.html#delete-branch[
Delete branch]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-projects.html#list-child-projects[
List child projects]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-projects.html#get-child-project[
Get child project]

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/rest-api-projects.html#set-config[
Set configuration]


Capabilities
~~~~~~~~~~~~


New global capabilities are added.

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/access_control.html#capability_generateHttpPassword[
Generate Http Password] allows non-administrator users to generate HTTP
passwords for users other than themselves.
+
This capability would typically be assigned to a non-interactive group
to be able to generate HTTP passwords for users from a tool or web service
that uses the Gerrit REST API.

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/access_control.html#capability_runAs[
Run As] allows users to impersonate other users by setting the `X-Gerrit-RunAs`
HTTP header on REST API calls.
+
Site administrators do not inherit this capability;  it must be granted
explicitly.


Emails
~~~~~~

* The `RebasedPatchSet` template is removed.  Email notifications for rebased
changes are now sent with the `ReplacePatchSet` template.

* Comment notification emails now include context of comments that are replied
to, and links to the file(s) in which comments are made.


Plugins
~~~~~~~


Global
^^^^^^


* Plugins may now contribute buttons to various parts of the UI using the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/dev-plugins.html#ui_extension[
UI extension] and
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/js-api.html[
JavaScript API].

* Plugins may now provide an 'About' section on their documentation index page.

* Plugins may now provide separate sections for REST API and servlet
documentation on their index page.

* Plugins may now provide
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-validation.html#pre-merge-validation[
pre-merge validation steps].

* Plugins may now provide
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/dev-plugins.html#capabilities[
Global capabilities].

* Plugins may now
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/dev-plugins.html#plugin_name[
define their own name] and get the name injected at runtime.

* The "hello world" plugin is replaced with the "cookbook plugin" which has more
examples of the plugin API's usage.

* Plugins may now trigger and listen to a "project deleted"
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/dev-plugins.html#events[
event].

* link:https://code.google.com/p/gerrit/issues/detail?id=2101[Issue 2101]:
Plugins implementing LifecycleListener can use auto registration.

* Plugins may bind REST endpoints with empty view names.

* Plugins may now provide
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/dev-plugins.html#top-menu-extensions[
entries in Gerrit's top menu].

* Plugins may now
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/dev-plugins.html#stream-events[
send events to the events stream].

* Plugins may now bind multiple SSH commands to the same implementation class.

* Plugins may now provide
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/dev-plugins.html#download-commands[
download schemes and download commands].
+
Commonly used download schemes and commands are moved out of core
Gerrit and are now implemented by a new core plugin, `download-commands`.


Commit Message Length Checker
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


* Commits whose subject or body length exceeds the limit can be rejected.

Replication
^^^^^^^^^^^

* Automatically create missing repositories on the destination.
+
If during the replication of a ref the target repository is found to be missing,
the repository is automatically created.
+
This is a change in behavior of the replication plugin. To go back to the old
behavior, set the parameter `remote.NAME.createMissingRepositories` in the
`replication.config` file to `false`.

* Support for replication of project deletions.
+
The replication plugin can now be configured to listen to project deletion events
and to replicate the project deletions. By default project deletions are *not*
replicated.

* The `{$name}` placeholder is optional when replicating a single project,
allowing a single project to be replicated under a different name.

* Project names can be matched with wildcard or regex patterns in `replication.config`.

* The `replication start` command does not exit until replication is finished
when the `--wait` option is used.

* The `replication start` command displays a summary of the replication status.

* Retry counts are added to replication task names, so they can be seen in the
output of the `show-queue` command.

* The `remoteNameStyle` option can be set to `basenameOnly` to replicate projects
using only the basename on the target server.

* The `startReplication` global capability is now provided by the plugin.

* Pushes to each destination URI are serialized.
+
Scheduling a retry to avoid collision with an in-flight push is differentiated
from a retry due to a transport error.  In the case of collision avoidance, the
job is rescheduled according to the replication delay, rather than the retry
delay.


ssh
~~~


* The `commit-msg` hook installation command is now
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-gerrit.html#gerrit.installCommitMsgHookCommand[
configurable].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/cmd-ls-members.html[
New `ls-members` command].

* link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/cmd-set-members.html[
New `set-members` command].
+
New command to manipulate group membership. Members can be added or removed
and groups can be included or excluded in one specific group or number of groups.

* The full commit message is now included in the data sent by the
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/cmd-stream-events.html[
`stream-events` command].

* The link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/cmd-show-queue.html[
`show-queue` command] now shows the time that a task was added to the queue.


Daemon
~~~~~~


* Add `--init` option to Daemon to initialize site on daemon start.
+
The `--init` option will also upgrade an already existing site and is processed in
non-interactive (batch) mode.


Bug Fixes
---------


General
~~~~~~~


* Use the parent change on the same branch for rebases.
+
Since there can be multiple changes with the same commit on different branches,
use the parent change on the same branch during rebase.

* link:https://code.google.com/p/gerrit/issues/detail?id=600[Issue 600]:
Fix change stuck in SUBMITTED state but actually merged.

* link:https://code.google.com/p/gerrit/issues/detail?id=1699[Issue 1699]:
Fix handling of projects with trailing ".git" suffix.

* Limit retrying of submitted changes to 12 hours.

* Don't allow project owners to delete branches if force push is blocked.

* Allow usernames to begin with digit.


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


* Do not persist default project state in `project.config`.

* Honor the `gerrit.cannonicalWebUrl` setting when opening the browser after init.

* Fix 'query disabled' error when Query Limit is set.

* Honor the `gerrit.createChangeId` setting from the git config in the
The link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/cmd-hook-commit-msg.html[
`commit-msg` hook].

* link:https://code.google.com/p/gerrit/issues/detail?id=2045[Issue 2045]:
Define user scope when parsing server config.

* link:https://code.google.com/p/gerrit/issues/detail?id=1990[Issue 1990]:
Support optional Certificate Revocation List (CRL) with `CLIENT_SSL_CERT_LDAP`.

* Do not override error and gc logging configuration provided by the
`-Dlog4j.configuration` parameter.

Web UI
~~~~~~


Global
^^^^^^


* link:https://code.google.com/p/gerrit/issues/detail?id=1574[Issue 1574]:
Correctly highlight matches of text in escaped HTML entities in suggestion results.

* link:https://code.google.com/p/gerrit/issues/detail?id=1996[Issue 1996]:
The "Keyboard Shortcuts" help popup can be closed by pressing the Escape key.

* link:https://code.google.com/p/gerrit/issues/detail?id=2013[Issue 2013]:
Correctly populate the list of watched changes when watching more than one project.

* Display "Working..." when header is hidden.

Change Screens
^^^^^^^^^^^^^^


* Default review comment visibility is changed to expand all recent.
+
By default all comments within the last week are expanded, rather than
only the most recent.

* link:https://code.google.com/p/gerrit/issues/detail?id=1814[Issue 1814]:
Sort labels alphabetically by name in the approval table.

* Don't add "This patchset was cherry picked to ..." for the same change.
+
If a patchset is cherry-picked to the same destination branch and
ends up on the same change, it does not make sense to add the "This
patchset was cherry picked to change ..." message.
+
In this case, it makes more sense for the message to say "Uploaded
patch set N" instead.

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


* Only enable the delete branch button when branches are selected.

* Disable the delete branch button while branch deletion requests are
still being processed.

User Profile Screens
^^^^^^^^^^^^^^^^^^^^


* The preferred email address field is shown as empty if the user has no
preferred email address.


REST API
~~~~~~~~


* Support raw input also in POST requests.

* Show granted date for labels/all when using `/changes/`.

* Return all revisions when `o=ALL_REVISIONS` is set on `/changes/`.

ssh
~~~


* The `--force-message` option is removed from the
The link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/cmd-review.html[
`review` command].

* link:https://code.google.com/p/gerrit/issues/detail?id=1908[Issue 1908]:
Provide more informative error messages when rejecting updates.

* Remove the limit in the query of patch sets by revision.

* Add `isDraft` in the `patchSet` attribute of `stream-events` data.
+
This allows consumers of the event stream to determine whether or not
the event is related to a draft patch set.

* Normalize the case of review labels submitted via the
The link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/cmd-review.html[
`review` command].

* The `@CommandMetaData(descr)` annotation is deprecated in favor of `@CommandMetaData(description)`.

* Improve the error message when rejecting upload for review to a read-only project.


Plugins
~~~~~~~

Global
^^^^^^

* Better error message when a Javascript plugin cannot be loaded.

* Plugin documentation links are opened in a new tab.

* The GitReferenceUpdatedListener.Event API is simplified.
+
The Event exposed the getUpdates method which implied that one Event
could contain updates of more than one reference. However, this feature
was never used.
+
The API is simplified in the sense that one Event now corresponds to
one ref update only.


Review Notes
^^^^^^^^^^^^

* Do not try to create review notes for ref deletion events.

* Fix committing the notes from the export command.

* link:https://code.google.com/p/gerrit/issues/detail?id=2087[Issue 2087]:
Fix note creation when the same commit exists in another Git repository.

* Improve the export command performance.

* Create review note also when newObjectId already present in another branch.

Emails
~~~~~~

* Email notifications are sent for new changes created via actions in the
Web UI such as cherry-picking or reverting a change.


Tools
~~~~~


* git-exproll.sh: return non-zero on errors


Documentation
-------------


* The link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/index.html[
documentation index page] is rewritten in a hierarchical structure.

* Documentation of
link:https://gerrit-documentation.storage.googleapis.com/Documentation/2.8/config-project-config.txt[
project configuration] is added.

* Various spelling mistakes are corrected in the documentation and previous
release notes.


Upgrades
--------

* Update JGit to 3.1.0.201310021548-r
* Update gwtorm to 1.7
* Update guice to 4.0-beta
* Update guava to 15.0
* Update H2 to 1.3.173
* Update bouncycastle to 1.44
* Update Apache Mina to 2.0.7
* Update Apache SSHD to 0.9.0.201311081
* asciidoctor 0.1.4 is now required to build the documentation
* jsr305 library was removed