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].


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]

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.


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.0.0.201306101825-r.41-g84d2738
* 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
* asciidoctor 0.1.4 is now required to build the documentation
* jsr305 library was removed