Release notes for Gerrit 2.0.21
===============================

Gerrit 2.0.21 is now available in the usual location:

link:http://code.google.com/p/gerrit/downloads/list[http://code.google.com/p/gerrit/downloads/list]


Schema Change
-------------

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

* The schema change may be difficult to undo once applied.
+
Downgrading could be very difficult once the upgrade has been
started.  Going back to 2.0.20 may not be possible.

* Do not run the schema change while the server is running.
+
This upgrade changes the primary key of a table, an operation
which shouldn't occur while end-users are able to make
modifications to the database.  I _strongly_ suggest a full
shutdown, schema upgrade, then startup approach for this release.

* There may be some duplicate keys
+
This upgrade removes a column from the primary key of a table,
which may result in duplicates being found.  You can search
for these duplicates before updating:
{{{
SELECT account_id,external_id FROM account_external_ids e
WHERE e.external_id IN (SELECT external_id
FROM account_external_ids
GROUP BY external_id
HAVING COUNT(*) > 1);
}}}
Resolving duplicates is left up to the administrator, in
general though you will probably want to remove one of the
duplicate records.  E.g. in one case I had 3 users with the
same mailing list email address registered.  I just deleted
those and sent private email asking the users to use their
personal/work address instead of a mailing list.
Apply the database specific schema script:
----
  java -jar gerrit.war --cat sql/upgrade017_018_postgres.sql | psql reviewdb
  java -jar gerrit.war --cat sql/upgrade017_018_mysql.sql    | mysql reviewdb
----


Important Notices
-----------------

* Prior User Sessions
+
The cookie used to identify a signed-in user has been changed.
Again.  All users will be automatically signed-out during
this upgrade, and will need to sign-in again after the upgrade
is complete.  The new schema has more room for extensions, so
this might be the last time we will need to invalidate sessions.

* Harmless error on first startup
+
Starting 2.0.21 on an instance which previously had the diff
cache stored on disk will result in the following non-fatal error
in the server logs during the first launch of .21 on that system:
----
2009-09-02 18:50:07,446::INFO : com.google.gerrit.server.cache.CachePool  - Enabling disk cache /home/gerrit2/android_codereview/disk_cache
Sep 2, 2009 6:50:07 PM net.sf.ehcache.store.DiskStore readIndex
SEVERE: Class loading problem reading index. Creating new index. Initial cause was com.google.gerrit.server.patch.DiffCacheKey
java.lang.ClassNotFoundException: com.google.gerrit.server.patch.DiffCacheKey
    at java.net.URLClassLoader$1.run(URLClassLoader.java:200)
    at java.security.AccessController.doPrivileged(Native Method)
    at java.net.URLClassLoader.findClass(URLClassLoader.java:188)
...
----
    This error can be safely ignored.  It is caused by a change
    in the diff cache's on disk schema, invalidating all existing
    cache entries.

* Significantly larger "diff" cache
+
The diff cache schema change noted above changed the element
stored in the cache from per-file to per-patchset.  That is,
a patch set which modifies 500 files will now occupy only 1
element in the diff cache, rather than 500 distinct elements.
Accordingly, the default `cache.diff.memoryLimit` setting has
been reduced to 128.

* Removed configuration settings
+
The following configuration settings are no longer honored:
`cache.maxAge`, `cache.memoryLimit`, `cache.diskLimit`, and
`cache.diskBuffer`.  These settings may now only be set on a
per-cache basis (e.g. `cache.diff.maxAge`).

* Connection pool recommendation: Apache Commons DBCP
+
All of the servers I run now use Apache Commons DBCP instead
of c3p0 for their connection pools, and the setup guide and
sample jetty_gerrit.xml reference DBCP now.
We've run into problems with c3p0 under high loads, or when
the connection pool is completely exhausted.  DBCP seems to
fail more gracefully, and seems to give us less trouble.
Changing pool implementations is not required, c3p0 is still
a supported provider.  I just want to make it clear that I no
longer recommend it in production.

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

* GERRIT-189  Show approval status in account dashboards
+
Account dashboards now show a summary of the approval status on
each change.  Unreviewed changes are now highlighted to bring
the reviewer's attention to them.  Tooltips when hovering over
a cell will bring up slightly more detailed information.

* GERRIT-276  Allow users to see what groups they are members of
+
Under Settings > Groups a user can now view what groups Gerrit
has placed them into.  This may help administrators to debug
a user's access problems, as they can ask the user to verify
Gerrit is seeing what they expect.

* GERRIT-276  Show simple properties of an LDAP group
+
If auth.type is HTTP_LDAP, groups which are marked as automatic
membership now show non-repeating LDAP attributes below their
description under Admin > Groups.  This display should help an
administrator to verify that Gerrit has mapped an LDAP group
correctly.

* Move Patch entity out of database and store in cache
+
The `patches` database table has been deleted, Gerrit now makes
the list of affected files on the fly and stores it within the
diff cache.  This change is part of a long-running series to
remove redundant information from the database before we switch
to a pure Git backed data storage system.

* Only copy blocking negative votes to replacement patch
+
Previously Gerrit copied any negative vote in any approval
category whenever a replacement patch set was uploaded to
a change.  Now Gerrit only copies "Code Review -2".
This change should make it easier for reviewers (and scripts
scanning `patch_set_approvals`) to identify updated changes
which might require a new review.
Adminstrators who have created their own categories and want to
copy the blocking negative vote should set `copy_min_score = 'Y'`
in the corresponding approval_categories records.

* show-caches: Make output more concise
+
Instead of showing ~12 lines of output per cache, each cache is
displayed as one line of a table.

* Handle multiple accountBase and groupBase
+
ldap.accountBase and ldap.groupBase may now be specified multiple
times in gerrit.config, to search more than one subtree within
the directory.

* Summarize collapsed comments
+
Collapsed comments (both inline on a file and on the change
itself) now show a short summary of the comment message, making
it faster to locate the relevant comment to expand for more
detailed reading.

* Edit inline drafts on Publish Comments screen
+
Inline comment drafts may now be directly edited on the Publish
Comments screen, which can be useful for fixing up a minor typo
prior to publication.

* Less toggly thingies on change screen
+
The change description and the approvals are no longer nested
inside of a foldy block.  Most users never collapse these, but
instead just scroll the page to locate the information they are
looking for.

* Restore Enter/o to toggle collapse state of comments
+
Enter and 'o' now expand or collapse an inline comment on the
the current row of a file.

* Display abbreviated hexy Change-Id in screen titles
* Use hexy Change-Id in emails sent from Gerrit
+
Change-Id abbreviations are now used throught more of the UI,
including emails sent by Gerrit and window/page titles.  This
change breaks email threading for any existing review emails.
That is comments on a change created before the upgrade will
not appear under the original change notification thread.

* Add sendemail.from to control setting From header
+
Gerrit no longer forges the From header in notification emails.
To enable the prior forging behavior, set `sendemail.from`
to `USER` in gerrit.config.  For more details see
link:http://gerrit.googlecode.com/svn/documentation/2.0/config-gerrit.html#sendemail.from[sendemail.from]

Bug Fixes
---------

* Fix ReviewDb to actually be per-request scoped
+
When we switched to Guice a misconfiguration allowed Guice to
give out multiple database connections per web or SSH request.
This could exhaust the connection pool faster than expected.

* Send no-cache headers during HTTP login
+
An oversight in the HTTP login code path may have allowed a proxy
server between the user's browser and the Gerrit server to cache
a user's session cookie.  Fixed by sending the correct no-cache
headers, disallowing any caching of the authentication response.

* Fix project owner permissions
+
Folks reported on repo-discuss that a project owner also had to
have READ permission to use the Branches tab of their project.
This was a regression introduced when we refactored some of the
code when adding Guice to the project.  Fixed.

* GERRIT-277  Fix hyperlinks in messages
+
Hyperlinks in commit messages such as "<http://foo>" were
including the trailing > in the URL, making the link broken.
The trailing > is now properly not included in the URL.

* GERRIT-266  Fix web session cookie refresh time
+
In 2.0.19 we introduced web sessions stored in Ehcache, but the
logic was causing sessions to expire roughly half-way through the
`cache.web_sessions.maxAge` time.  At the default setting, active
sessions were expiring after 6 hours.  The cache management has
been refactored to make this a lot less likely.

* Cleanup not signed in error to be more user friendly
+
The error message which comes up when your session is expired
is now much more useful.  From the dialog you can restart your
session by clicking the "Sign-In" button, and return to the
screen you are currently on.

* Fix commit-msg hook to work with commit -v option
+
The commit-msg hook was buggy and did not handle `git commit -v`
correctly.  It also did some bad insertions, placing the magic
`Change-Id: I...` line at the wrong position in the commit
message.  The updated hook resolves most of these problems,
but must be recopied to individual Git repositories by end-users.

* Identify PGP configuration errors during startup
+
If the encrypted contact store is enabled, the required encryption
algorithms are checked at startup to ensure they are enabled
in the underlying JVM.  This is necessary in case the JVM is
updated and the administrator forgot to install the unlimited
strength policy file in the new runtime directory.  Recently
review.source.android.com was bitten by just such an upgrade.

* GERRIT-278  Fix missing reply comments on old patch set
+
Some comments were not visible because they were replies made
to a comment on say patch set 1 while looking at the difference
between patch set 1 and patch set 2 of a change.  Fixed.

* Make external_id primary key of account_external_ids
+
The database schema incorrectly allowed two user accounts to have
the same email address, or to have the same OpenID auth token.
Fixed by asserting a unique constraint on the column.

Other Changes
-------------
* Start 2.0.21 development
* Support cleaning up a Commons DBCP connection pool
* Clarify which Factory we are importing in ApproveComma...
* Avoid loading Patch object in /cat/ servlet
* Remove unnecessary reference of patch key in save draft
* GERRIT-266  Tweak cache defaults to be more reasonable
* Merge change I131e6c4c
* Bring back the "No Differences" message when files are...
* Pick up gwtorm 1.1.2-SNAPSHOT
* Refactor GroupListScreen's inner table for reuse
* Do not normalize approval scores on closed changes in ...
* Don't obtain 0 approvals or submit approvals in dashbo...
* Update JGit to 0.5.0-93-g5b89a2c
* Add tests for Change-Id generating commit-msg hook
* Add test for commit-msg with commit -v
* Fix formatting error in ApprovalCategory
* Fix typo in change table column header "Last Update"
* Fix reference to the All Projects broken when we remov...
* Use category abbreviations in the dashboard approval c...
* Format approvals columns in change tables with minimal...
* Shrink the Last Updated column in dashboards and chang...
* Highlight changes which need to be reviewed by this us...
* Fix typo in ChangeTable comment
* Reduce the window used for "Mon dd" vs. "Mon dd yyyy" ...
* Don't assume "Anonymous Users" and "Registered Users" ...
* Log encrypted contact store failures
* Identify PGP configuration errors during startup
* Take the change description block out of the disclosure...
* Move the approval table out of a disclosure panel
* Explicitly show what value is needed to submit
* Modernize the display of comments on a change
* Modernize the display of inline comments on a file
* Fix "Publish Comments" when there are no inline drafts
* Merge change 11666
* Fix display of "Gerrit Code Review" authored comments
* Fix source code formatting error in FormatUtil
* Remove unnecessary fake author on inline comments
* Auto expand all drafts on publish comments screen
* Remove unused local variable in PublishCommentsScreen
* Remove unused import from PublishCommentsScreen
* Use gwtorm, gwtexpui release versions
* Add javadoc for Change.getKey
* Updated documentation for eclipse development.
* Merge change 11698
* Merge change 11699
* Merge change 11700
* Merge change 11703
* Merge change 11705
* Moved creation of GerritPersonIdent to a separate provi...
* Remove unused dependency on GerritServer.
* Renamed GerritServert to GitRepositoryManager and moved...
* Remove declaration of OrmException that is never thrown.
* Increase margin space between buttons of comment editors
* Simplify GerritCallback error handling
* Correct comment documenting SignInDialog
* Remove unused CSS class gerrit-ErrorDialog-ErrorMessage
* Clarify become any account servlet errors
* Fix anchor in sshd.reuseAddress documentation
* Extract parametrized string formatting out of LdapQuery
* Make cache APIs interfaces for mocking
* Add easymock 2.5.1 to our test dependencies
* Add sendemail.from to control setting From header
* gerrit 2.0.21