= Release notes for Gerrit 2.2.2

Gerrit 2.2.2 is now available:

link:https://www.gerritcodereview.com/download/gerrit-2.2.2.war[https://www.gerritcodereview.com/download/gerrit-2.2.2.war]

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

*WARNING:* Upgrading to 2.2.x requires the server be first upgraded
to 2.1.7 (or a later 2.1.x version), and then to 2.2.x.

== New Features

=== Prolog
* issue 971 Use Prolog Cafe for ChangeControl.canSubmit()

*  Add per-project prolog submit rule files
+
When loading the prolog environment, now checks refs/meta/config
branch for a file called rules.pl. If it exists, consult the
file. Expects a predicate called submit_rule. If no file is found,
uses the default_submit predicate in common_rules.pl.

*  Add inheritance of prolog rules
+
Projects now inherit the prolog rules defined in their parent
project. Submit results from the child project are filtered by the
parent project using the filter predicate defined in the parent's
rules.pl. The results of the filtering are then passed up to the
parent's parent and filtered, repeating this process up to the top
level All-Projects.

* Load precompiled prolog rules from jar file
+
Looks in (site)/cache/rules for a jar file called:
  rules-(sha1 of rules.pl).jar
Loads the precompiled prolog rules and uses them instead of
consulting rules.pl. If the jar does not exist, consults rules.pl.
If rules.pl does not exist, uses the default submit rules.

* Cmd line tool rulec to compile jar from prolog
+
Rulec takes rules.pl from the refs/meta/config branch and creates a
jar file named rules-(sha1 of rules.pl).jar in (sitepath)/cache/rules.
Generates temporary prolog, java src, and class files which are
deleted afterwards.

* prolog-shell: Simple command line Prolog interpreter
+
Define a small interactive interpreter that users or site
administrators can play around with by downloading the Gerrit WAR
file and executing: java -jar gerrit.war prolog-shell

==== Prolog Predicates
*  Add Prolog Predicates to check commit messages and edits
+
commit_message returns the commit message as a symbol.
+
commit_message_matches takes in a regex pattern and checks it against
the commit message.
+
commit_edits takes in a regex pattern for filenames and a regex
pattern for edits. For all files in a commit that match the filename
regex.  Returns true if the edits in any of those files match the
edit regex.

* Add Prolog  Predicates to expose commit filelist
+
commit_delta/1,3,4 each takes a regular expression and matches it to
the path of all the files in the latest patchset of a commit.
If applicable (changes where the file is renamed or copied), the
regex is also checked against the old path.
+
commit_delta/1 returns true if any files match the regex
+
commit_delta/3 returns the changetype and path, if the changetype is
renamed, it also returns the old path. If the changetype is rename,
it returns a delete for oldpath and an add for newpath. If the
changetype is copy, an add is returned along with newpath.
+
commit_delta/4 returns the changetype, new path, and old path
 (if applicable).

* Add Prolog predicates that expose the branch, owner,
project, and  topic of a change, the author and committer of the most
recent patchset in the change, and who is the current user.

* For user-related predicates, if the user is not a gerrit user, will
return user(anonymous) or similar. Author and committer predicates
for commits return user(id), name, and email.

* Make max_with_block/4 public
+
This is the current rule generally applied to a label function. Make
it exportable for now until we can come back and clean up the legacy
approval data code.

=== Web

* Support in Firefox delete key in NpIntTextBox
+
Pressing the delete key while being in a NpIntTextBox (e.g. in the
text box for the Tab Width or Columns preference when comparing a
file) now works in Firefox.

* Make sure special keys work in text fields
+
There is a bug in gwt 2.1.0 that prevents pressing special keys like
Enter, Backspace etc. from being properly recognized and so they have no effect.

==== ChangeScreen
* issue 855 Indicate outdated dependencies on the ChangeScreen
+
If a change dependency is no longer the latest patchSet for that
change, mark it OUTDATED in the dependencies table and make
its row red, and add a warning message to the dependencies
header, also keep the dependencies disclosure panel open
even when an outdated dependent change is merged.
Additionally make the link for dependencies link to the
exact patchSet of the dependent change.

* issue 881 Allow adding groups as reviewer
+
On the ChangeScreen it is now possible to add a group as reviewer for
a change. When a group is added as reviewer the group is resolved and
all its members are added as reviewers to the change.

* Update approvals in web UI to adapt to rules.pl submit_rule
+
The UI now shows whatever the results of the submit_rule are, which
permits the submit_rule to make an ApprovalCategory optional, or to
make a new label required.

==== Diff Screen
* Add top level menus for a new PatchScreen header
+
Modify the PatchScreen so that the header contents is selectable
using top level menus. Allow the header to display the commit
message, the preferences, the Patch Sets, or the File List.

* Add SideBySide and Unified links to Differences top level menus
+
These new menu entries allow a user to switch view types easily
without returning to the ChangeScreen.  Also, they double as a
way to hide the header on the PatchScreen (when clicking on the
currently displayed type).

* Add user pref to retain PatchScreen Header when changing files

* Flip the orientation of PatchHistory Table

* Remove the 'Change SHA1:' from the PatchScreen title

* Remove scrollbar from Commit Message

* Allow comment editing with single click on line numbers
+
Make it easier to comment (and now possible on android devices which
zoom on double click) on a patch by simply clicking on the line number.

* Add a "Save" button to the PatchScriptSettingsPanel
+
The "Update" button now only updates the display.  Additionally,
for logged in users, a "Save" button now behaves the way that
"Update" used to behave for logged in users.

* issue 665 Display merge changes as differences from automatic result
+
Instead of displaying nothing for a two-parent merge commit, compute
the automatic merge result and display the difference between the
automatic result that Git would create, and the actual result that
was uploaded by the author/committer of the merge.

==== Groups
* Add menu to AccountGroupScreen
+
This change introduces a menu in the AccountGroupScreen and
different screens for subsets of the functionality (similar as it's
done for the ProjectScreen).  Links from other screens to the
AccountGroupScreen are resolved depending on the group type.

* Display groupUUID on AccountGroupInfoScreen
+
To assign a privilege to a new group by editing the
'project.config' file, the new group needs to be added to the
'groups' file in the 'refs/meta/config' branch which requires
the UUID of the group to be known.

==== Project Access
* Automatically add new rule when adding new permission
+
If a new permission was added to a block, immediately create the new
group entry box and focus it, so the user can assign the permission.

* Only show Exclusive checkbox on reference sections
+
In the access editor, hide the Exclusive checkbox on the
Global Capabilities section since it has no inheritance and
the exclusive bit isn't supported.

* Disable editing after successful save of Access screen
+
When the access has been successfully modified for a project,
switch back to the "read-only" view where the widgets are all
disabled and the Edit button is enabled.

==== Project Branches
* Display refs/meta/config branch on ProjectBranchesScreen
+
The new refs/meta/config branch was not shown in the ProjectBranchesScreen.
Since refs/meta/config is not just any branch, but has a special
meaning to Gerrit it is now displayed at the top below HEAD.

* Highlight HEAD and refs/meta/config
+
Since HEAD and refs/meta/config do not represent ordinary branches,
highlight their rows with a special style in the ProjectBranchesScreen.

==== URLs
* Modernize URLs to be shorter and consistent
+
Instead of http://site/#change,1234 we now use a slightly more
common looking   http://site/#/c/1234  URL to link to a change.
+
Files within a patch set are now denoted below the change, as in
http://site/#/c/1234/1/src/module/foo.c
+
Also fix the dynamic redirects of http://site/1234
and http://site/r/deadbeef to jump directly to the corresponding
change if there is exactly one possible URL.
+
Entities that have multiple views suffix the URL with ",view-name"
to indicate which view the user wants to see.

* issue 1018 Accept ~ in linkify() URLs

=== SSH
* Added a set-reviewers ssh command

* Support removing more than one reviewer at once
+
This way we can batch delete reviewers from a change.

* issue 881 Support adding groups as reviewer by SSH command
+
With the set-reviewers SSH command it is now possible to also add
groups as reviewer for a change.

* Fail review command for changing labels when change is closed
+
If a reviewer attempts to change a review label (approval) after a
change is closed using the ssh review command, cause it to fail the
command and output a message.

* ls-projects: Fix display of All-Projects under --tree
+
Everything should be nested below All-Projects, since that is actually
the root level.

* ls-projects: Add --type to filter by project type
+
ls-projects now supports --type code|permissions|all.  The default is
code which now skips permissions only projects, restoring the output
to what appears from Gerrit 2.1.7 and earlier.

* show-caches: Improve memory reporting
+
Change the way memory is reported to show the actual values,
and the equation that determines how these are put together
to form the current usage.  Include some additional data including
server version, current time, process uptime, active SSH
connections, and tasks in the task queue. The --show-jvm option
will report additional data about the JVM, and tell the caller
where it is running.

==== Queries
* Output patchset creation date for 'query' command.

* issue 1053 Support comments option in query command
+
Query SSH command will show all comments if option --comments is
used. If --comments is used together with --patch-sets all inline
comments are included in the output.

=== Config
* Move batch user priority to a capability
+
Instead of using a magical group, use a special capability to
denote users that should get the batch priority behavior.

* issue 742 Make administrator, create-project a global capability
+
This gets rid of the special entries in system_config and
gerrit.config related to who the Administrators group is,
or which groups are permitted to create new projects on
this server.

* issue 48 & 742  Add fine-grained capabilities for administrative actions
+
The Global Capabilities section in All-Projects can now be used to
grant subcommands that are available over SSH and were previously
restricted to only Administrators.

* Disallow project names ending in "/"

* issue 934 query: Enable configurable result limit
+
Allow site administrators to configure the query limit for user to be
above the default hard-coded value of 500 by adding a global
[capability] block to All-Projects project.config file with group(s)
that should have different limits.

* Introduced a new PermissionRule.Action: BLOCK.
+
Besides already existing ALLOW and DENY actions this change
introduces the BLOCK action in order to enable blocking some
permission rules globally.

* issue 813 Use remote.name.replicatePermissions to hide permissions
+
Administrators can now disable replication of permissions-only
projects and the per-project refs/meta/config in replication.config
by setting the replicatePermissions field to false.

* Add a Restored.vm template and use it.
+
The restore action has been erroneously using the Abandoned.vm
template.  Create a template and sender for the restorecommand.

* sshd.advertisedAddress: specify the displayed SSH host/port
+
This allows aliases which redirect to gerrit's ssh port (say
from port 22) to be setup and advertised to users.

=== Dev
* Updated eclipse settings for 3.7 and m2e 1.0

* Fix build in m2eclipse 1.0
+
Ignore the antrun and the build-helper-maven-plugin tasks in m2eclipse.

* Make Gerrit with gwt 2.3.0 run in gwtdebug mode

* Fix a number of build warnings that have crept in

* Accept email address automatically
+
Enable Gerrit to accept email address automatically in
"DEVELOPMENT_BECOME_ANY_ACCOUNT" mode without a confirmation email.

* Added clickable user names at the BecomeAnyAccountLoginServlet.
+
The first 5 (by accountId) user names are displayed as clickable
links. Clicking a user name logs in as this user, speeding up
switching between different users when using the
DEVELOPMENT_BECOME_ANY_ACCOUNT authentication type.

=== Miscellaneous
* Permit adding reviewers to closed changes
+
Permit adding a reviewer to closed changes to support post-submit
discussion threads.

* issue 805 Don't check for multiple change-ids when pushing directly
to refs/heads.

* Avoid costly findMergedInto during push to refs/for/*
+
No longer close a change when a commit is pushed to res/for/* and the
Change-Id in the commit message footer matches another commit on an
existing branch or tag.

* Allow serving static files in subdirectories

* issue 1019 Normalize OpenID URLs with http:// prefix
+
No longer violate OpenID 1.1 and 2.0, both of which require
OpenIDs to be normalized (http:// added).

* Allow container-based authentication for git over http
+
Gerrit was insisting on DIGEST authentication when doing git over
http. A new boolean configuration parameter auth.trustContainerAuth
allows gerrit to be configured to trust the container to do the
authentication.

* issue 848 Add rpc method for GerritConfig
+
Exposes what types of reviews are possible via json rpc, so that the
Eclipse Reviews plugin currently can parse the javascript from a
gerrit page load.


== Performance
* Bumped Brics version to 1.11.8
+
This Brics version fixes a performance issue in some larger Gerrit systems.

* Add permission_sort cache to remember sort orderings
+
Cache the order AccessSections should be sorted in, making any future
sorting for the same reference name and same set of section patterns
cheaper.

* Refactor how permissions are matched by ProjectControl, RefControl
+
More aggressively cache many of the auth objects at a cost of memory,
but this should be an improvement in response times.

* Substantially speed up pushing changes for review
+
Pushing a new change for review checks if the change is related to
the branch it's destined for. It used to do this in a way that
required a topo-sort of the rev history, and now uses JGit's
merge-base functionality.

* Add cache for tag advertisements
+
To make the general case more efficient, introduce a cache called "git_tags".
+
On a trivial usage of the Linux kernel repository, the average
running time of the VisibleRefFilter when caches were hot was
7195.68 ms.  With this commit, it is a mere 5.07 milliseconds
on a hot cache.  A reduction of 99% of the running time.

* Don't set lastCheckTime in ProjectState
+
The lastCheckTime/generation fields are actually a counter that
is incremented using a background thread. The values don't match
the system clock, and thus reading System.currentTimeMillis()
during the construction of ProjectState is a waste of resources.


== Upgrades
* Upgrade to GWT 2.3.0
* Upgrade to Gson to 1.7.1
* Upgrade to gwtjsonrpc 1.2.4
* Upgrade to gwtexpui 1.2.5
* Upgrade to Jsch 0.1.44-1
* Upgrade to Brics 1.11.8


== Bug Fixes
* Fix: Issue where Gerrit could not linkify certain URLs

* issue 1015 Fix handling of regex ref patterns in Access panel
+
regex patterns such as "\^refs/heads/[A-Z]{2,}\-[0-9]\+.\*" were being
prefixed with "refs/heads/", resulting in invalid reference patterns
like "refs/heads/^refs/heads/[A-Z]{2,}-[0-9]+.*".

* issue 1002 Check for and disallow pushing of invalid refs/meta/config
+
If the project.config or groups files are somehow invalid on
the refs/meta/config branch, or would be made invalid due to
a bad code review being submitted to this branch, reject the
user's attempt to push.

* issue 1002 Fix NPE in PermissionRuleEditor when group lacks UUID
+
If a group does not have an entry in the "groups" table within
the refs/meta/config branch render the group name as a span,
without the link instead of crashing the UI.

* issue 972 Filter access section rules to only visible groups
+
Users who are not the owner of an access section can now only
see group names and rules for groups which they are a member of,
are visible to all users, or that they own.

* Correctly handle missing refs/meta/config branch
+
If the refs/meta/config branch did not exist, getRevision() no longer
throws an NPE when trying to access the ProjectDetail.

* Allow loading Project Access when there is no refs/meta/config
+
Enable loading the access screen with a null revision field,
and on save of any edits require the branch to be new.

* create-project: Fix creation vs. replication order
+
Create the project on remote mirrors before creating either the
refs/meta/config or the initial empty branch. This way those can be
replicated to the remote mirrors once they have been created locally.

* create-project: Bring back --permissions-only flag
+
If a project is permissions only, assign HEAD to point to
refs/meta/config. This way the gitweb view of the project
shows the permissions history by default, and clients that
clone the project are able to get a detached HEAD pointing
to the current permission state, rather than an empty
repository.

* create-project: Fix error reporting when repository exists
+
If a repository already exists, tell the user it already is
available, without disclosing the server side path from gerrit.basePath.

* Do not log timeout errors on upload and receive connections

* Only automatically create accounts for LDAP systems
+
If the account management is LDAP, try to automatically create
accounts by looking up the data in LDAP. Otherwise fail and reject an
invalid account reference that was supplied on the command line via
SSH.

* Add missing RevWalk.reset() after checking merge base
+
This fixes an exception from RevWalk when trying to push a new
commit for review.

* issue 1069 Do not send an email on reviews when there is no message.
+
No longer send an email when reviewing a change via ssh, and
the change message is blank (when no change message is actually
added to the review).

* Ignore PartialResultException from LDAP.
+
This exception occurs when the server isn't following referrals for
you, and thus the result contains a referral. That happens when
you're using Active Directory. You almost certainly don't really want
to follow referrals in AD *anyways*, so just ignore these exceptions,
so we can still use the actual data.

* issue 518 Fix MySQL counter resets
+
gwtorm 1.1.5 was patched to leave in the dummy row that incremented
the counter, ensuring the server will use MAX() + 1 instead of 1 on
the next increment after restart.

* Don't delete account_id row on MySQL
+
If the table is an InnoDB table deleting the row after allocation may
cause the sequence to reset when the server restarts, giving out
duplicate account_ids later.


== Documentation

=== New Documents
* First Cut of Gerrit Walkthrough Introduction documentation.
+
Add a new document intended to be a complement for the existing
reference documentation to allow potential users to easily get a
feel for how Gerrit is used, where it fits and whether it will
work for them.

* Introducing a quick and dirty setup tutorial
+
The new document covers quick installation, new project and first
upload.  It contains lots of quoted output, with a demo style to it.

=== Access Control
* Code review

* Conversion table between 2.1 and 2.2
+
Add a table to ease conversion from 2.1.x. The table tries to address
the old permissions one by one except for the push tag permission which
in effect needed two permissions to work properly. This should
be familiar to the administrator used to the 2.1.x permission model
however.

* Reformatted text

* Verify
+
Updated some text in the Per project-section and edited the verified
section to reflect the current label.

* Capabilities
+
Adds general information about global capabilities, how the server
ownership is administered.

* Added non-interactive users
+
This change adds the non-interactive user group.
It also adds that groups can be members of other groups.
The groups are now sorted in alphabetical order.

* Reordering categories
+
Access categories are now sorted to match drop down box in UI

=== Other Documentation
* Added additional information on the install instructions.
+
The installation instructions presumes much prior knowledge,
make some of that knowledge less implicit.

* Provides a template to the download example.
+
Clarifies that the example host must be replaced with proper
hostname.

* Provided an example on how to abandon a change from
the command line

* update links from kernel.org to code.google.com


* Rename '-- All Projects --' in documentation to 'All-Projects'

* Explain 'Automatically resolve conflicts'

* Update documentation for testing SSH connection
+
The command output that is shown in the example and the description
how to set the ssh username were outdated.

* Remove unneeded escape characters from the documentation
+
The old version of asciidoc required certain characters to be escaped
with a backslash and when the upgrade to the new version was done all
those backslashes that were used for escaping became visible.

* Clean up pgm-index
+
Break out the utilities into their own section, and correct
some of the item descriptions.

* Update manual project creation instructions

* Update project configuration documentation
+
Remove the textual reference to obsolete SQL insert statement to
create new projects.

* Clean up command line documentation, examples
+
The formatting was pretty wrong after upgrading to a newer version
of AsciiDoc, so fix up most of the formatting, correct some order
of commands in the index, and make create-project conform to the
same format used by create-account and create-group.

* Correct syntax of SQL statement for inserting approval category