Release notes for Gerrit 2.6
============================

Gerrit 2.6 is now available:

link:http://code.google.com/p/gerrit/downloads/detail?name=gerrit-2.6.war[http://code.google.com/p/gerrit/downloads/detail?name=gerrit-2.6.war]

Gerrit 2.6 includes the bug fixes done with
link:ReleaseNotes-2.5.1.html[Gerrit 2.5.1] and
link:ReleaseNotes-2.5.2.html[Gerrit 2.5.2]. These bug fixes are *not*
listed in these release notes.

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

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

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

Review UI
~~~~~~~~~
* The reviewer matrix on a change displays gray boxes where
  permissions do not allow voting in that category. The coloring
  enables authors to quickly identify if another reviewer is
  necessary to continue the change.

* New 'Rebase If Necessary' submit type. This is similar to cherry
  pick, but honors change dependency information.

* The submit type that is used for submitting a change is shown on the
  change screen in the info block.
+
This is useful because the submit type of a change can now be
link:#submit-type-from-prolog[controlled by Prolog].

* The rebase button is hidden when the patch set is current.

* `suggest.from` configures a minimum number of characters before
  matches for reviewers, accounts, groups or projects are offered.

* A change's topic can be added, removed or changed from the
  change screen.

* A change's commit message can be edited from the change screen.

* The patch set review screen can include radio buttons for custom
  labels if enabled by
  link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/prolog-cookbook.html#_how_to_write_submit_rules[submit rules].


Access Controls
~~~~~~~~~~~~~~~
* Allow to overrule `BLOCK` permissions on the same project
+
It was impossible to block a permission for a group and allow the same
permission for a sub-group of that group as the `BLOCK` permission
always won over any `ALLOW` permission. For example, it was impossible
to block the "Forge Committer" permission for all users and then allow
it only for a couple of privileged users.
+
An `ALLOW` permission has now  priority over a `BLOCK` permission when
they are defined in the same access section of a project. To achieve the
above mentioned policy the following could be defined:
+
  [access "refs/heads/*"]
    forgeCommitter = block group Anonymous Users
    forgeCommitter = group Privileged Users
+
Across projects the `BLOCK` permission still wins over any `ALLOW`
permission. This way one cannot override an inherited `BLOCK`
permission in a subproject.
+
Overruling of `BLOCK` permissions with `ALLOW` permissions also works
for labels i.e. permission ranges. If a dedicated 'Verifiers' group
need to be the only group who can vote in the 'Verified' label and it
must be ensured that even project owners cannot change this policy,
then the following can be defined in a common parent project:
+
  [access "refs/heads/*"]
    label-Verified = block -1..+1 group Anonymous Users
    label-Verified = -1..+1 group Verifiers

* link:https://code.google.com/p/gerrit/issues/detail?id=1516[issue 1516]:
  Show global capabilities to all users that can read `refs/meta/config`
+
Users can now propose changes to the global capabilities for review
from the WebUI.

* link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/access-control.html#category_remove_reviewer[
  Remove Reviewer] is a new permission.

* link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/access-control.html#category_push_signed[
  Pushing a signed tag] is a new permission.

* link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/access-control.html#category_edit_topic_name[
  Editing the topic name] is a new permission.

* link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/access-control.html#capability_accessDatabase[
  Raw database access] with the `gsql` command is a new global capability.
+
Previously site administrators had this capability by default.  Now it has
to be explicitly assigned, even for site administrators.

* link:https://code.google.com/p/gerrit/issues/detail?id=1585[Issue 1585]:
  link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/access-control.html#category_view_drafts[
  Viewing other users' draft changes] is a new permission.

* link:https://code.google.com/p/gerrit/issues/detail?id=1675[Issue 1675]:
  link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/access-control.html#category_delete_drafts[Deleting] and
  link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/access-control.html#category_publish_drafts[publishing]
  other users' draft changes is a new permission.

* link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/config-gerrit.html#ldap.groupName[
  LDAP group names] are configurable, `cn` is still the default.

* Kerberos authentication to LDAP servers is now supported.

* Basic project properties are now inherited by default from parent
  projects: Use Content Merge, Require Contributor Agreement, Require
  Change Id, Require Signed Off By.

* Allow assigning `Push` for `refs/meta/config` on `All-Projects`
+
The `refs/meta/config` branch of the `All-Projects` project should only
be modified by Gerrit administrators because being able to do
modifications on this branch means that the user could assign himself
administrator permissions.
+
In addition to being administrator Gerrit requires that the
administrator has the `Push` access right for `refs/meta/config` in
order to be able to modify it (just as with all other branches
administrators do not have edit permissions by default).
+
The problem was that assigning the `Push` access right for
`refs/meta/config` on the `All-Projects` project was not allowed.
+
Having the `Push` access right for `refs/meta/config` on the
`All-Projects` project without being administrator has no effect.

Hooks
~~~~~
* Change topic is passed to hooks as `--topic NAME`.
* link:https://code.google.com/p/gerrit/issues/detail?id=1200[Issue 1200]:
New `reviewer-added` hook and stream event when a reviewer is added.

* link:https://code.google.com/p/gerrit/issues/detail?id=1237[Issue 1237]:
New `merge-failed` hook and stream event when a change cannot be submitted due to failed merge.

* link:https://code.google.com/p/gerrit/issues/detail?id=925[Issue 925]:
New `ref-update` hook run before a push is accepted by Gerrit.

SSH
~~~
* New SSH command to http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/cmd-gc.html[
  run Git garbage collection]
+
All GC runs are logged in a GC log file.

* Descriptions are added to ssh commands.
+
If `gerrit` is called without arguments, it will now show a list of available
commands with their descriptions.

* `create-account --http-password` enables setting/resetting the
  HTTP password of role accounts, for Git or REST API access.

* http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/cmd-ls-user-refs.html[
  ls-user-refs] lists which refs are visible for a given user.

* `ls-projects --has-acl-for` lists projects that mention a group
  in an ACL, identifying where rights are granted.

* `review` command supports project-specific labels

* `test-submit-rule` was renamed to `test-submit rule`:
+
`rule` is now a subcommand of the `test-submit` command.

* http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/cmd-test-submit-type.html[
  test-submit type] tests the Prolog submit type with a chosen change.

Query
~~~~~
* Allow `{}` to be used for quoting in query expressions
+
This makes it a little easier to query for group names that contain
a space over SSH:
+
  ssh srv gerrit query " 'status:open NOT reviewerin:{Developer Group}' "

* The query summary block includes `resumeSortKey`.

* Query results include author and change size information when certain
  options are specified.

* When a file is renamed the old file name is included in the Patch
  attribute

Plugins
~~~~~~~
* Plugins can contribute Prolog facts/predicates from Java.
* Plugins can prompt for parameters during `init` with `InitStep`.
* Plugins can now contribute JavaScript to the web UI. UI plugins can
  also be written and compiled with GWT.
* New Maven archetypes for JavaScript and GWT plugins.
* Plugins can contribute validation steps to received commits.
* Commit message length checks are moved to the `commit-message-length-validator`
  plugin which is included as a core plugin in the Gerrit distribution and
  can be installed during site initialization.

Prolog
~~~~~~
[[submit-type-from-prolog]]
* link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/prolog-cookbook.html#HowToWriteSubmitType[
  Support controlling the submit type for changes from Prolog]
+
Similarly like the `submit_rule` there is now a `submit_type` predicate
which returns the allowed submit type for a change. When the
`submit_type` predicate is not provided in the `rules.pl` then the
project default submit type is used for all changes of that project.
+
Filtering the results of the `submit_type` is also supported in the
same way like filtering the results of the `submit_rule`. Using a
`submit_type_filter` predicate one can enforce a particular submit type
from a parent project.

* Plugins can contribute Prolog facts/predicates from Java.

* link:https://code.google.com/p/gerrit/issues/detail?id=288[Issue 288]:
  Expose basic commit statistics for the Prolog rule engine
+
A new method `gerrit:commit_stats(-Files,-Insertions, -Deletions)` was
added.

* A new `max_with_block` predicate was added for more convenient usage

Email
~~~~~
* Notify project watchers if draft change is published
* Notify users mentioned in commit footer on draft publish
* Add new notify type that allows watching of new patch sets
* link:https://code.google.com/p/gerrit/issues/detail?id=1686[Issue 1686]:
  Add new notify type that allows watching abandoning of changes
* link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/user-notify.html[
  Notifications configured in `project.config`] can now be addressed
  using any of To, CC, or BCC headers.
* link:https://code.google.com/p/gerrit/issues/detail?id=1531[Issue 1531]:
Email footers now include `Gerrit-HasComments: {Yes|No}`.
* `#if($email.hasInlineComments())` can be used in templates to test
  if there are comments to be included in this email.
* Notification emails are sent to included groups.
* Comment notification emails are sent to project watchers.
* "Change Merged" emails include the diff output when `sendemail.includeDiff` is enabled.
* When link:http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/rest-api-changes.html#set-review[
  posting a review via REST] the caller can control email delivery
+
This may help automated systems to be less noisy. Tools can now choose
which review updates should send email, and which categories of users
on a change should get that email.

Labels
~~~~~~
* Approval categories stored in the database have been replaced with labels
  configured in `project.config`. Existing categories are migrated to
  `project.config` in `All-Projects` as part of the schema upgrade; no user
  action is required.
* Labels are no longer global; projects may define their own labels,
  with inheritance.

Performance
~~~~~~~~~~~
* Bitmap Optimizations
+
On running the http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/cmd-gc.html[
garbage collection] Jgit creates bitmap data that is saved to an
auxiliary file. The bitmap optimizations improve the clone and fetch
performance. git-core will ignore the bitmap data.

* Improve suggest user performance when adding a reviewer.
+
Do not check the visibility of the change for each suggested account if
the ref is visible by all registered users.
+
On a system with about 2-3000 users, where most of the projects are
visible by every registered user, this improves the performance of the
suggesting reviewer by a factor of 1000 at least.

* Cache RefControl.isVisible()
+
For Git repositories with many changes the time for calculating visible
refs is reduced by 30-50%.

* Allow admins to disable magic ref check on upload
+
Some sites manage to run their repositories in a way that prevents
users from ever being able to create `refs/for`, `refs/drafts` or
`refs/publish` names in a repository. Allow admins on those servers
to disable this (somewhat) expensive check before every upload.

* Permit ProjectCacheClock to be completely disabled
+
Some admins may just want to require all updates to projects to be
made through the web interface, and avoid the small expense of a
background thread ticking off changes.

* Batch read Change objects during query

* Default `core.streamFileThreshold` to a larger value
+
If this value is not configured by the server administrator
performance on larger text files suffers considerably and
Gerrit may grind to a halt and be unable to answer users.
+
Default to either 25% of the available JVM heap or ~2048m.

* Improve performance of ReceiveCommits for repositories with many refs
+
Avoid adding `refs/changes/` and `refs/tags/` to RevWalk's as
uninteresting since JGit RevWalk doesn't perform well when a large
number of objects is marked as uninteresting.

* PatchSet.isRef()-optimizations.
+
PatchSet.isRef() is used extensively when preparing for a ref
advertisment and the regular expression used by isRefs() was notably
costly in these circumstances, especially since it could not be
pre-compiled.
+
The regular expression is removed and the check is now directly
implemented. As result the performance of `git ls-remote` could be
increased upto 15%.

* New config option `receive.checkReferencedObjectsAreReachable`
+
If set to true, Gerrit will validate that all referenced objects that
are not included in the received pack are reachable by the user.
+
Carrying out this check on Git repositories with many refs and commits
can be a very CPU-heavy operation. For non public Gerrit servers it may
make sense to disable this check, which is now possible.

* Cache config value in LdapAuthBackend

* Perform a single /accounts/self/capabilities on page load
+
This joins up 3 requests into a single call, which should speed up
initial page load for most users.

* Only gzip compress responses that are smaller compressed

* Caching of changes
+
During Ref Advertisments (via VisibleRefFilter), all changes need to
be fetched from the database to allow Gerrit to figure out which change
refs are visible and should be advertised to the user. To reduce
database traffic a cache for changes was introduced. This cache is
disabled by default since it can mess-up multi-server setups.

Upgrades
~~~~~~~~
* link:https://code.google.com/p/gerrit/issues/detail?id=1619[Issue 1619]:
Embedded Jetty is now 8.1.7.v20120910.

* ASM bytecode library is now 4.0.
* JGit is now 2.3.1.201302201838-r.78-g8fcde4b.
* asciidoc 8.6.3 is now required to build the documentation.
* link:https://code.google.com/p/gerrit/issues/detail?id=1155[Issue 1155]:
prettify is now r225

Bug Fixes
---------

Web UI
~~~~~~
* Links to CGit were broken when `remove-suffix` was enabled.
* link:https://code.google.com/p/gerrit/issues/detail?id=926[Issue 926]:
Internet Explorer versions 9 and 10 are supported.

Git
~~~
* The wildcard `.` is now permitted in reference regex rules.
* Checking if a change is mergeable no longer writes to the repository.
* Improved `git ls-remote` and `git fetch` performance by caching
  changes, decreasing database queries and traffic.
* link:https://code.google.com/p/gerrit/issues/detail?id=1608[Issue 1608]:
Commits pushed without a Change-Id now warn with instructions on how
to download and install the commit-msg hook.

* Submitted but unmerged changes are periodically retried. This is
  necessary for a multi-master configuration where the second master
  may need to retry a change not yet merged by the first. Please note
  we still do not believe this is sufficient to enable multi-master.

* Added a server-level option to use JGit's new, experimental recursive
  merger.

SSH
~~~
* `review --restore` allows a review score to be added on the restored change.

* link:https://code.google.com/p/gerrit/issues/detail?id=1721[Issue 1721]:
  `review --message` only adds the message once.

* `ls-groups` prints "N/A" if the group's name is not set.

* `set-project-parent --children-of`: Fix getting parent for level 1 projects
+
For direct child projects of the `All-Projects` project the name of the
parent project was incorrectly retrieved if the parent name was not
explicitly stored as `All-Projects` in the project.config file.

Query
~~~~~
* link:https://code.google.com/p/gerrit/issues/detail?id=1729[Issue 1729]:
  Fix query by 'label:Verified=0'

* link:https://code.google.com/p/gerrit/issues/detail?id=1772[Issue 1772]:
  Set `_more_changes` if result is limited due to configured query limit

* Fix query cost for "status:merged commit:c0ffee"

Email
~~~~~
* Merge failure emails are only sent once per day.
* Unused macros are removed from the mail templates.
* Unnecessary ellipses are no longer applied to email subjects.
* The empty diff output from an "octopus merge" is now explained in change notification emails.
* link:https://code.google.com/p/gerrit/issues/detail?id=1480[Issue 1480]:
Proper error message is shown when registering an email address fails.

* link:https://code.google.com/p/gerrit/issues/detail?id=1692[Issue 1692]:
Review comments are sorted before being added to notification emails.

* Fix watching of 'All Comments' on `All-Projects`
+
If a user is watching 'All Comments' on `All-Projects` this should
apply to all projects.

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

User Documentation
~~~~~~~~~~~~~~~~~~

* Added documentation of how to authenticate uploads over HTTP.
* Added documentation of the `auth.editFullNameUrl` and `auth.httpPasswordUrl` configuration parameters.
* Improved the push tag examples in the access control documentation.
* Improved documentation of error messages related to commit message footer content.
* Added documentation of the "commit already exists" error message.
* Added documentation of contributor agreements.
* Added missing documentation of JSON attributes.
* Added missing documentation of mail templates.
* Added missing documentation of the ssh `version` command.
* link:https://code.google.com/p/gerrit/issues/detail?id=1602[Issue 1602]:
Corrected references to `refs/changes` in the access control documentation.

* Various minor grammatical and formatting corrections.
* Manual pages can be optionally created/installed for core gerrit ssh commands.

Developer And Maintainer Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Updated the Maven plugin installation instructions for Eclipse 3.7 (Indigo).
* Improved the release documentation.
* The release notes are now made when a release is created by running the `tools/release.sh` script.