gerrit/ReleaseNotes/ReleaseNotes-2.0.19.txt

= Release notes for Gerrit 2.0.19, 2.0.19.1, 2.0.19.2

Gerrit 2.0.19.2 is now available in the usual location:

link:https://www.gerritcodereview.com/download/index.html[https://www.gerritcodereview.com/download/index.html]

== Important Notices

* Prior User Sessions
+
The cookie used to identify a signed-in user has been changed.  All users
will be automatically signed-out during this upgrade, and will need to
sign-in again after the upgrade is complete.
Users who try to use a web session from before the upgrade may receive the
obtuse error message "Invalid xsrfKey in request".  Prior web clients are
misinterpreting the error from the server.  Users need to sign-out and
sign-in again to pick up a new session.
This change was necessary to close GERRIT-83, see below.

* Preserving Sessions Across Restarts
+
Administrators who wish to preserve user sessions across server restarts must
set [http://gerrit.googlecode.com/svn/documentation/2.0/config-gerrit.html#cache.directory cache.directory] in gerrit.config.  This allows Gerrit to flush the set
of active sessions to disk during shutdown, and load them back during startup.

== Schema Change

*WARNING: This version contains a schema change* (since 2.0.18)

Important notes about this schema change:

* Do not run the schema change while the server is running.
+
This upgrade adds a new required column to the changes table, something
which cannot be done while users are creating records. Like .18, I _strongly_
suggest a full shutdown, schema upgrade, then startup approach.
Apply the database specific schema script:
----
  java -jar gerrit.war --cat sql/upgrade016_017_postgres.sql | psql reviewdb
  java -jar gerrit.war --cat sql/upgrade016_017_mysql.sql    | mysql reviewdb
----


== New Features
* New ssh create-project command
+
Thanks to Ulrik Sjölin we now have `gerrit create-project`
available over SSH, to construct a new repository and database
record for a project.  Documentation has also been updated to
reflect that the command is now available.

* Be more liberal in accepting Signed-off-by lines
+
The "Require Signed-off-by line" feature in a project is now
more liberal.  Gerrit now requires that the commit be signed off
by either the author or the committer.  This was relaxed because
kernel developers often cherry-pick in patches signed off by
the author and by Linus Torvalds, but not by the committer who
did the backport cherry-pick.

* Allow cache.name.diskLimit = 0 to disable on disk cache
+
Setting cache.name.diskLimit to 0 will disable the disk for
that cache, even though cache.directory was set.  This allows
sites to set cache.diff.diskLimit to 0 to avoid caching the diff
records on disk, but still allow caching web_sessions to disk,
so that live sessions are maintained across server restarts.
This is a change in behavior, the prior meaning of diskLimit =
0 was "unlimited", which is not very sane given how Ehcache
manages the on disk cache files.

* Allow human-readable units in config.name.maxage
+
Timeouts for any cache.name.maxAge may now be specified in human
readable units, such as "12 days" or "3 hours".  The server will
automatically convert them to minutes during parsing.  If no
unit is specified, minutes are assumed, to retain compatibility
with prior releases.

* Add native LDAP support to Gerrit
+
Gerrit now has native LDAP support.  Setting auth.type to
HTTP_LDAP and then configuring the handful of ldap properties
in gerrit.config will allow Gerrit to load group membership
directly from the organization's LDAP server.  This replaces
the need for the sync-groups script posted in the wiki.  See:
link:http://gerrit.googlecode.com/svn/documentation/2.0/config-gerrit.html#ldap[http://gerrit.googlecode.com/svn/documentation/2.0/config-gerrit.html#ldap]
If you use the sync-groups script from the wiki page, you would
also need to delete the group members after upgrading, to remove
unnecessary records in your database:
{{{
DELETE FROM account_group_members
WHERE group_id IN (
SELECT group_id FROM account_groups
WHERE automatic_membership = 'Y');
}}}

* Don't allow users to edit their name if it comes from LDAP
+
User information loaded from LDAP, such as full name or SSH
username, cannot be modified by the end-user.  This allows the
Gerrit site administrator to require that users conform to the
standard information published by the organization's directory
service.  Updates in LDAP are automatically reflected in Gerrit
the next time the user signs-in.

* Remembers anchor during HTTP logins
+
When using an HTTP SSO product, clicking on a Gerrit link received
out-of-band (e.g. by email or IM) often required clicking the
link twice.  On the first click Gerrit redirect you to the
organization's single-sign-on authentication system, which upon
success redirected to your dashboard.  The actual target of the
link was often lost, so a second click was required.
With .19 and later, if the administrator changes the frontend web
server to perform authentication only for the /login/ subdirectory
of Gerrit, this can be avoided.  For example with Apache:
----
     <Location "/login/">
       AuthType Basic
       AuthName "Gerrit Code Review"
       Require valid-user
       ...
     </Location>
----
   During a request for an arbitrary URL, such as '/#change,42',
   Gerrit realizes the user is not logged in.  Instead of sending an
   immediate redirect for authentication, Gerrit sends JavaScript
   to save the target token (the part after the '#' in the URL)
   by redirecting the user to '/login/change,42'.  This enters
   the secured area, and performs the authentication.  When the
   authenticated user returns to '/login/change,42' Gerrit sends
   a redirect back to the original URL, '/#change,42'.


* Create check_schema_version during schema creation
+
Schema upgrades for PostgreSQL now validate that the current
schema version matches the expected schema version at the start
of the upgrade script.  If the schema does not match, the script
aborts, although it will spew many errors.

* Reject disconnected ancestries when creating changes
+
Uploading commits to a project now requires that the new commits
share a common ancestry with the existing commits of that project.
This catches and prevents problems caused by a user making a typo
in the project name, and inadvertently selecting the wrong project.

* Change-Id tags in commit messages to associate commits
+
Gerrit now looks for 'Change-Id: I....' in the footer area of a
commit message and uses this to identify a change record within
the project.
If the listed Change-Id has not been seen before, a new change
record is created.  If the Change-Id is already known, Gerrit
updates the change with the new commit.  This simplifies updating
multiple changes at once, such as might happen when rebasing an
entire series of commits that are still being reviewed.
A commit-msg hook can be installed to automatically generate
these Change-Id lines during initial commit:
{{{
scp -P 29418 review.example.com:hooks/commit-msg .git/hooks/
}}}
Using this hook ensures that the Change-Id is predicatable once
the commit is uploaded for review.
For more details, please see the docs:
link:http://gerrit.googlecode.com/svn/documentation/2.0/user-changeid.html[http://gerrit.googlecode.com/svn/documentation/2.0/user-changeid.html]

== Bug Fixes
* Fix yet another ArrayIndexOutOfBounds during side-by-s...
+
We found yet another bug with the side-by-side view failing
under certain conditions.  I think this is the last bug.

* Apply URL decoding to parameter of /cat/
* Fix old image when shown inline in unified diff
+
Images weren't displaying correctly, even though
mimetype.image/png.safe was true in gerrit.config.
Turned out to be a problem with the parameter decoding of the
/cat/ servlet, as well as the link being generated wrong.

* Fix high memory usage seen in `gerrit show-caches`
+
In Gerrit 2.0.18 JGit had a bug where the repository wasn't being
reused in memory.  This meant that we were constantly reloading
the repository data in from disk, so the server was always maxed
out at core.packedGitLimit and core.packedGitOpenFiles, as no
data was being reused from the cache.  Fixed in this release.

* Fix display of timeouts in `gerrit show-caches`
+
Timeouts were not always shown correctly, sometimes 12 hours
was showing up as 2.5 days, which is completely wrong.  Fixed.

* GERRIT-261  Fix reply button when comment is on the last line
+
The "Reply" button didn't work if the comment was on the last
line of the file, the browser caught an array index out of
bounds exception as we walked off the end of the table looking
for where to insert the new editor box.

* GERRIT-83   Make sign-out really invalidate the user's session
+
The sign-out link now does more than delete the cookie from the
user's browser, it also removes the token from the server side.
By removing it from the server, we prevent replay attacks where
an attacker has observed the user's cookie and then later tries
to issue their own requests with the user's cookie.  Note that
this sort of attack is difficult if SSL is used, as the attacker
would have a much more difficult time of sniffing the user's
cookie while it was still live.

* Evict account record after changing SSH username
+
Changing the SSH username on the web immediately affected the
SSH daemon, but the web still showed the old username.  This
was due to the change operation not flushing the cache that
the web code was displaying from.  Fixed.

* Really don't allow commits to replace in wrong project
+
It was possible for users to upload replacement commits to the
wrong project, e.g. uploading a replacement commit to project
B while picking a change number from project A.  Fixed.

== =Fixes in 2.0.19.1=

* Fix NPE during direct push to branch closing a change
+
Closing changes by pushing their commits directly into the branch didn't
always work as expected, due to some data not being initialized correctly.

* Ignore harmless "Pipe closed" in scp command
+
scp command on the server side threw exceptions when a client aborted the
data transfer.  We typically don't care to log such cases.

* Refactor user lookup during permission checking
* GERRIT-264  Fix membership in Registered Users group
+
Users were not a member of "Registered Users", this was a rather serious
bug in the code as it meant many users lost their access rights.

* GERRIT-265  Correctly catch "Invalid xsrfKey in request" error as ...
+
Above I mentioned we should handle this error as "Not Signed In", only
the pattern match wasn't quite right.  Fixed.

* GERRIT-263  Fix --re=bob to match bob@example.com when using HTTP_LDAP
+
HTTP_LDAP broke using local usernames to match an account.  Fixed.

== =Fixes in 2.0.19.2=
* Don't line wrap project or group names in admin panels
+
Line wrapping group names like "All Users" when the description column
has a very long name in it is ugly.

* GERRIT-267  Don't add users to a change review if they cannot access
+
If a user cannot access a change, let the owner know when they try to
add the user as a reviewer, or CC them on it.

* commit-msg: Do not insert Change-Id if the message is ...
+
The commit-msg hook didn't allow users to abort accidental git commit
invocations, as it still modified the file, making git commit think
that the end-user wanted to make a commit.  Anyone who has a copy of
the hook should upgrade to the new hook, if possible.

* Support recursive queries against LDAP directories
* Fix parsing of LDAP search scope properties
+
As reported on repo-discuss, recursive search is sometimes necessary,
and is now the default.

== Removed Features

* Remove support for /user/email style URLs
+
I decided to remove this URL, its a pain to support and not
discoverable.  Its unlikely anyone is really using it, but if
they are, they could try using "#q,owner:email,n,z" instead.

== Other Changes

* Start 2.0.19 development
* Document the Failure and UnloggedFailure classes in Ba...
* Merge change 11109
* Document gerrit receive-pack is alias for git receive-...
* Define a simple query language for Gerrit
* Create new projects on remote systems with mkdir -p
* Set the GIT_DIR/description file during gerrit create-...
* Remove unnecessary toLowerCase calls in AdminCreatePro...
* Remove unnecessary exception from AdminCreateProject
* Remove unused import from AccountExternalId
* Abstract out account creation and simplify sign-on for...
* Implement server side sign-out handling
* Cleanup private keys in system_config table
* Remove dead max_session_age field from system_config
* Report 'Invalid xsrfKey' as 'Not Signed In'
* Update gerrit flush-caches documentation about web_ses...
* Update documentation on cache "web_sessions" configura...
* Add getSchemeRest to AccountExternalId
* Cleanup ContactStore and WebModule injection
* Catch Bouncy Castle Crypto not installed when loading ...
* Declare caches in Guice rather than hardcoded in Cache...
* Remove old commented out cache configuration code
* Don't NPE in SSH keys panel when SSHD is bound to loca...
* Don't send users to #register,register,mine
* Document the new LDAP support
* Cleanup section anchors to be more useful
* Put anchors on every configuration variable section
* Add missing AOSP copyright header to WebSession
* Fix short header lines in gerrit-config.txt
* Update documentation about system_config private key f...
* Fetch groups from LDAP during user authentication
* Actually honor cache.ldap_groups.maxage
* Add enum parsing support to ConfigUtil
* Rename LoginType to AuthType
* Support loading the sshUserName from LDAP
* Change ldap.accountDisplayName to ldap.accountFullName
* Fix parsing set-to-nothing options in ldap section
* Report more friendly errors from gwtjsonrpc
* Ensure dialog box displays correctly on network failure
* Document how setting LDAP properties disables web UI
* Ensure the commit body is parsed before getting the co...
* Cleanup more section anchors
* Make documentation table of contents anchors human rea...
* Remove notes about HTML 5 offline support
* Fix typo in LegacyGerritServlet javadoc
* Use subList in server side change query code
* Remove unsupported /all_unclaimed
* Rewrite UrlRewriteFilter in terms of Guice bindings
* Create a commit-msg hook to generate Change-Id tags
* Add change_key to changes table in database
* Allow searching for changes by Change-Id strings
* Display the change key, aka Change-ID in the informati...
* Display abbreviated change ids in change lists
* Change javax.security AccountNotFoundException to NoSu...
* Automatically update existing changes during refs/for/...
* Automatically close changes when pushing into a branch...
* Document the new commit-msg hook supplied by Gerrit
* Correct title of "Command Line Tools" documentation pa...
* Correct URL example used in Google Analytics Integrati...
* Correct comment about customizing categories and caches
* Fix formatting of remote.name.timeout section in docum...
* Add anchors for remote settings in replication.config ...
* Widen the search panel now that Change-Ids are 41 char...
* Revert "Ensure dialog box displays correctly on networ...
* Allow searches for Change-Ids starting with lowercase ...
* Fix line wrapped formatting in ChangeListServiceImpl
* Move Change.Key abbreviation to Change.Key class
* Format change ids in listing tables with a fixed with ...
* Cleanup documentation of the commit-msg hook
* Cleanup the command line tool index page
* Correct stale documentation section about SSH authenti...
* Correct access control documentation about project own...
* Quote the current directory when running asciidoc
* Move the Default Workflow link into the top of the Use...
* Correct formatting of usage in gerrit-cherry-pick docu...
* Document how Gerrit uses Change-Id lines
* Add Change-Id lines during cherry-pick if not already ...
* Fix "no common ancestry" bug
* Fix commit-msg hook to handle first lines like "foo: f...
* Add a link to Gerrit's project to the top of gerrit-ch...
* Add full ASLv2 copyright notice to commit-msg hook
* Embed Gerrit's version number into shell scripts copie...
* Don't drop max_session_age column in transaction durin...
* gerrit 2.0.19