blob: 472f0dcc5d1c7387547b632aa1118876557588ac [file] [log] [blame]
= Release notes for Gerrit 2.8
Gerrit 2.8 is now available:
== 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`.
*WARNING:* The deprecated `approve` alias for the
review] SSH command has been removed. This is important for all users
of the Jenkins link:[
Gerrit Trigger Plugin] since this plugin by default uses the `approve`
command to vote and comment on changes in Gerrit. If you use the Gerrit
Trigger Plugin, go to its global configuration in Jenkins and adapt the
Gerrit commands to use the `review` command instead of the `approve`
*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 during the
site initialization].
== Release Highlights
* link:[
New change screen] with completely redesigned UI and fully using the REST API.
* link:[
Secondary indexing with Lucene and Solr].
* Lots of new link:[
REST API endpoints].
* New
UI extension] and
JavaScript API] for plugins.
* New build system using Facebook's link:[Buck].
* New core plugin: Download Commands.
== New Features
=== Build
* Gerrit is now built with
* Documentation is now built with Buck and link:[Asciidoctor].
=== Indexing and Search
Gerrit can be configured to use a
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
`comment` search operator].
* The link:[
`file` operator] can be used to find changes on the specified file.
* Regular expressions are allowed in `file` searches.
*WARNING:* After enabling the secondary index, the index must be built using the
reindex program] before restarting the Gerrit server.
=== Configuration
* Project owners can define `receive.maxObjectSizeLimit` in the
project configuration] to further reduce the global setting.
* Site administrators can define a
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
site initialization command].
* New `auth.httpDisplaynameHeader` and `auth.httpEmailHeader` in the
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:[
Customizable registration page for HTTP authentication].
* link:[
Configurable external `robots.txt` file].
* Support for
Oracle database].
* New bash completion script for autocompletion of parameters to the wrapper.
* The site can be
auto-initialized on server startup].
* link:[
Configurable filtering of HTTP traffic through Gerrit's HTTP protocol].
* Labels can be
configured to copy scores forward to new patch sets if there is no code change].
* Labels can be
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
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:[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
* 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.
* Several new link:[
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:[
List access rights for project(s)]
==== Accounts
* link:[
Create account]
* link:[
Get account full name]
* link:[
Set account full name]
* link:[
Delete account full name]
* link:[
List account email addresses]
* link:[
Get account email address]
* link:[
Set account preferred email address]
* link:[
Create account email]
* link:[
Delete account email]
* link:[
Get account state]
* link:[
Set account state to active]
* link:[
Set account state to inactive]
* link:[
Get account HTTP password]
* link:[
Set or generate account HTTP password]
* link:[
Delete account HTTP password]
* link:[
List account SSH keys]
* link:[
Get account SSH key]
* link:[
Add account SSH key]
* link:[
Delete account SSH key]
* link:[
Get account username]
* link:[
Get starred changes]
* link:[
Star change]
* link:[
Unstar change]
==== Changes
* link:[
Rebase change]
* link:[
Cherry-pick revision]
* link:[
Get content of a file in a revision]
* link:[
Get revision as a formatted patch]
* link:[
Get diff of a file in a revision]
* link:[
Get parsed commit of a revision]
* link:[
Publish draft change]
* link:[
Delete draft change]
* link:[
Suggest reviewers]
* link:[
Get included in]
==== Config
* link:[
Get capabilities]
* link:[
Get version] (of the Gerrit server)
==== Projects
* link:[
List branches]
* link:[
Get branch]
* link:[
Create branch]
* link:[
Delete branch]
* link:[
List child projects]
* link:[
Get child project]
* link:[
Set configuration]
=== Capabilities
New global capabilities are added.
* link:[
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:[
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
=== 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
UI extension] and
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
pre-merge validation steps].
* Plugins may now provide
Global capabilities].
* Plugins may now
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:[Issue 2101]:
Plugins implementing LifecycleListener can use auto registration.
* Plugins may bind REST endpoints with empty view names.
* Plugins may now provide
entries in Gerrit's top menu].
* Plugins may now
send events to the events stream].
* Plugins may now bind multiple SSH commands to the same implementation class.
* Plugins may now provide
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*
* link:[Issue 1880]:
Make `{name}` placeholder optional when replicating a single project.
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
=== ssh
* The `commit-msg` hook installation command is now
* link:[
New `ls-members` command].
* link:[
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
`stream-events` command].
* The link:[
`show-queue` command] now shows the time that a task was added to the queue.
* The deprecated `approve` alias of the `review` command is removed.
* The 'CHANGEID,PATCHSET' format for specifying a patch set in the `review` command
is no longer considered to be a 'legacy' feature that will be removed in future.
=== 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:[Issue 600]:
Fix change stuck in SUBMITTED state but actually merged.
* link:[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.
* Verify access to source ref during add branch operation.
Previously Gerrit didn't check access to source ref during add branch
operation. Because of that users could create a branch from any known
commit SHA1, even when they didn't have access to that commit.
* Fix Gerrit API sources JAR contents.
The gerrit-extension-api-X.Y-all-sources.jar did not actually contain any
* Generate javadoc for Gerrit Extension and Plugin APIs.
* link:[Issue 2244]:
Update patch status before skipping duplicate emails.
* link:[Issue 1640]:
Catch missing LDAP accounts in group membership.
* Use `rev-parse` to find gitdir when generating commit-msg hook hint.
* Performance Fix: Minimize number of advertisedHaves.
By filtering the refs before the objectIds are added to advertisedHaves,
lots of time can be saved when pushing to complex Gits.
=== Configuration
* Do not persist default project state in `project.config`.
* Honor the `gerrit.canonicalWebUrl` 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
`commit-msg` hook].
* link:[Issue 2045]:
Define user scope when parsing server config.
* link:[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.
* Fix JdbcSQLException when numbers are read from cache.
=== Web UI
==== Global
* link:[Issue 1574]:
Correctly highlight matches of text in escaped HTML entities in suggestion results.
* link:[Issue 1996]:
The "Keyboard Shortcuts" help popup can be closed by pressing the Escape key.
* link:[Issue 2013]:
Correctly populate the list of watched changes when watching more than one project.
* Display "Working..." when header is hidden.
* link:[Issue 2125]:
Correctly shows '-1' instead of '1' for label score.
If a user voted '-1', and then another user voted '+1' for a label, the
label was shown as a red '1' in the change list instead of red '-1'.
==== 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:[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.
* Make links appear with consistent colors.
* Prevent duplicate permitted_labels from being shown in labels list.
==== Diff Screens
* link:[Issue 1233]:
Prevent expansion when whole file isn't loaded.
* link:[Issue 2122]:
Show review comments for unchanged files.
When comparing patch sets and some comment was put in one side,
that comment was not shown if there was no code changed between
the two patch sets
==== 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.
* 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:[
`review` command].
* link:[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:[
`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.
* Make plugin servlet's context path authorization aware.
==== Review Notes
* Do not try to create review notes for ref deletion events.
* Fix committing the notes from the export command.
* link:[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.
* Correct documentation of the export command.
=== Emails
* Email notifications are sent for new changes created via actions in the
Web UI such as cherry-picking or reverting a change.
=== Tools
* return non-zero on errors
== Documentation
* The link:[
documentation index page] is rewritten in a hierarchical structure.
* Documentation of
project configuration] is added.
* Various spelling mistakes are corrected in the documentation and previous
release notes.
* link:[Issue 2144]:
Documentation of the query operator is fixed.
== Upgrades
* Update JGit to
* 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
* link:[Issue 2232]:
Update Apache SSHD to
* asciidoctor 0.1.4 is now required to build the documentation
* jsr305 library was removed
* link:[Issue 2232]:
Update Jsch to 1.5.0