==============================
Review Board 1.6 Release Notes
==============================

**Release date**: September 5, 2011


This release contains all bug fixes and features found in
Review Board version :doc:`1.5.6 <1.5.6>`.


New User Features
=================

Review Requests
---------------

Close Descriptions
~~~~~~~~~~~~~~~~~~

When closing a review request (discarding or marking as submitted), a
description can now be added on the close banner. This works much like
a change description for drafts. These can be used to describe why a change
was discarded, or what revision it was submitted as, or anything else.

Patch by Hongbin Lu. (:bug:`268`, :bug:`693`, :bug:`1052`)

See the :ref:`closing-review-requests` documentation for more information.


Collapsible Reviews
~~~~~~~~~~~~~~~~~~~

Older reviews that haven't been updated since the last time you accessed the
review request are now collapsed, letting you focus on the latest discussions
taking place.

Collapsed reviews can be expanded by clicking the :guilabel:`[+]` button.

Patch by Kevin Quinn.


Notification Tab Icons
~~~~~~~~~~~~~~~~~~~~~~

The page icon shown on the tab will now show a green indicator whenever there's
an update notification on the page. This makes it easier to keep track of any
changes to review requests when several tabs are open.


Data Loss Prevention
~~~~~~~~~~~~~~~~~~~~

It's harder to lose the changes you make to a review request. We have
several safe-guards to keep from accidentally losing work.

* Added error messages when typing an invalid reviewer (user or group).
  Prior to this, the invalid reviewer would just disappear from the list,
  leaving no indication that it was wrong.

  Patch by Kevin Quinn.

* Added alerts whenever leaving a page would cause data loss. (:bug:`1794`)

  Leaving a page while a field or a comment or anything else is being
  edited will now prompt the user to make them aware they may lose changes.
  They'll have an option to leave the page or stay on the page.

* Added confirmation when canceling a field with new changes. (:bug:`2096`)

* Added a :kbd:`Control-S` shortcut to save the field you're editing.

  Patch by Hongbin Lu. (:bug:`2096`)


File Attachments
----------------

Files of any type can now be uploaded to a review request and reviewed
as a whole. This is useful for providing tarballs of non-diffable files,
log files, unit test output, sample files, etc.

Every uploaded file will appear on the review request page, with the
ability to download or add a comment about the file.

Comments made on files will appear in the review, just like diff and
screenshot comments.

Like screenshots, file attachments can be dragged and dropped from the
file manager into the review request as a faster way to upload them.

The initial work for this feature was developed by Laila Agaev and then
Steve Sutcliffe as part of their UCOSP_ projects this past year.

See the :ref:`uploading-files` documentation for more information.

.. _UCOSP: http://www.ucosp.ca/


Review Improvements
-------------------

Quick Ship It!
~~~~~~~~~~~~~~

A new :guilabel:`Ship It!` button on the action bar of a review request makes
it easier to post new "Ship It!" reviews. It takes only two clicks to post
the review. One to click the button, and another to confirm you want to post
the review. This greatly speeds up reviews of good changes.

See the :ref:`quick-ship-it` documentation for more information.

Patch by Kevin Quinn. (:bug:`1640`)


Issue Tracking
~~~~~~~~~~~~~~

Issue tracking provides a new and improved way to mark and reply to defects in
a change. When reviewing code, a reviewer can mark a comment as a defect
by checking the :guilabel:`Open an issue` checkbox in a comment dialog. The
developer will see that an issue has been filed, and can easily mark it as
fixed, or drop it.

This is a faster way to reply to reviews. The developer needs only to click
a button to say the issue was fixed, instead of replying with a comment saying
it's fixed.

See the :ref:`issue-tracking` documentation for more information.

Patch by Mike Conley.


Persistent Draft Banners
~~~~~~~~~~~~~~~~~~~~~~~~

Review draft banners now stay on screen while the review is shown.

This helps with long reviews when you've reached a point where you want to
publish the review. You no longer need to scroll up to find the draft banner.
It will remain on screen.

Patch by Mark Striemer.


Diff Viewer
-----------

Delete Detection
~~~~~~~~~~~~~~~~

Deleted files in Git and Perforce are now specifically shown as having been
deleted in the diff viewer, instead of the entire file being shown in red.
In time, we'll extend this to other types of repositories.


Move/Rename Information
~~~~~~~~~~~~~~~~~~~~~~~

The change index and file sections now show when a file has been moved or
renamed and what the new name is. Whether or not this is shown depends on the
diff and type of repository.

Patch by Colin Caughie.


User Profiles
-------------


Private Profiles
~~~~~~~~~~~~~~~~

Added support for private profiles.

On a public Review Board server, users may not want their name and e-mail
address to be easily accessed on their profile page or through the API.  Users
can now go to their My Account page and make their profile private.

When a profile is private, the only users who can see the profile information
are the site administrators and the user owning the profile.

Patch by Hongbin Lu. (:bug:`2127`)


Improved User Pages
~~~~~~~~~~~~~~~~~~~

The user page now shows more information on the user, such as their name,
e-mail address, their Gravatar_, and what groups they're a member of.  Patch
by Kevin Quinn.


User Info Bubbles
~~~~~~~~~~~~~~~~~

Hovering the mouse of a user's name (either on a review or review request)
now loads an info bubble showing the user's name, e-mail address, and
Gravatar_.

Patch by Kevin Quinn.

.. _Gravatar: http://www.gravatar.com/


Search
------

Quick search
~~~~~~~~~~~~

The search field is now always shown, and will search as you type.  Unlike the
full-text search (which will happen when clicking :guilabel:`Search`, if
full-text search is enabled), this will only search users (by username, first
name or last name), groups (group name or display name), or review requests
(numeric ID or summary).

See the :ref:`quick-search` documentation for more information.

Patch by Crystal Lok Koo. (:bug:`1842`)


Search by Change Number
~~~~~~~~~~~~~~~~~~~~~~~

Users can now search for review requests by Perforce change numbers. Note that
this may require a full reindex.

Patch by Crystal Lok Koo. (:bug:`1508`)


Dashboard
---------

New Columns
~~~~~~~~~~~

New People and Groups columns were added to the dashboard. These new columns
show the individual and group reviewers listed for review requests. They
are optional and need to be explicitly added.

Patch by Philipp Henkel.


Color-Coded Labels
~~~~~~~~~~~~~~~~~~

The "Discarded" and "Submitted" labels in the dashboard views now have their
own distinct colors.

Patch by Vlad Filippov. (:bug:`1903`)


Better E-Mail Filtering
-----------------------

Added ``X-ReviewGroup`` headers for e-mails, which lists all the review
groups assigned in the review request. E-mail clients can use this to
filter review requests into different folders.

Patch by Vignesh Srinivasan. (:bug:`1964`)


SCM Improvements
----------------

New Clear Case Support
~~~~~~~~~~~~~~~~~~~~~~

Added a brand new Clear Case implementation.

This new implementation is cleaner, more reliable, and fixes many of the
problems with the old implementation. Given that this is a complete rewrite,
we'd appreciate any bug reports for things that used to work in Review Board
1.5.x.

Patch by Jan Koprowski. (:bug:`1375`, :bug:`1516`, :bug:`1553`, :bug:`1588`,
:bug:`1599`, :bug:`1644`, :bug:`1727`, :bug:`1926`, :bug:`1930`, :bug:`1931`).


New Administration Features
===========================

Access Control
--------------

Local Site Divisions
~~~~~~~~~~~~~~~~~~~~

Review Board now supports managing several virtual instances within a single
install, similar to subdirectory installs but as part of a main install's URL.
These would live on, for example, ``http://reviews.example.com/s/mysitename/``,
where ``http://reviews.example.com/`` is the main Review Board installation.

These site divisions can all have their own repositories, groups, review
requests, users, and administrators. Data within a site division is available
only to members of that site. This makes it easy to have, say, a main
development Review Board, a contractor Review Board, and a QA Review Board,
all separate and locked down, but without having to maintain and upgrade
multiple servers.

This isn't completely put together yet. An administrator on a site doesn't yet
have any UI for putting together a repository or changing any settings, so it
still requires a site-wide administrator to set up each site division.

This is an advanced feature and may not work for all use cases yet.


Invite-only Groups
~~~~~~~~~~~~~~~~~~

Groups can now be marked as invite-only. An invite-only group cannot be viewed
by non-members of the group through either the web or the UI.

A review request targetting just invite-only groups cannot be viewed unless
the user is either explicitly specified on the review request or they're a
member of at least one of the targetted groups. However, if it also lists any
public groups, it will be available to everyone.

Note that users will still be able to see these review requests listed on the
"All Review Requests" page, but won't be able to access them.

See the :ref:`invite-only-review-groups` documentation for more information.


Hidden Groups
~~~~~~~~~~~~~

Hidden groups are groups that are not shown unless a user is a member or
otherwise knows about it (for example, has starred the group, or knows the
URL). A hidden group may be invite-only, but it doesn't have to be.

This allows administrators to deprecate a group or to hide invite-only groups.
The group won't appear in any auto-complete, list, or the API, unless the user
is a member of the group.

See the :ref:`hidden-review-groups` documentation for more information.


Private Repositories
~~~~~~~~~~~~~~~~~~~~

Repositories can now be locked down such that only specific users can see the
review requests on them. Users can be added to a repository's user list
directly, or indirectly by adding one or more invite-only groups. Note that
access control applies to the entire repository, not specific paths within it.

If a user doesn't have access to a private repository, they won't be able to
see any review requests on it.

See the :ref:`private-repositories` documentation for more information.


E-mail
------

DKIM Support
~~~~~~~~~~~~

Some spam filters would get caught up on Review Board's :mailheader:`From`
header forging. The address didn't actually match the source, causing them to
sometimes flag review requets as spam.

We now send e-mails with a :mailheader:`Sender` header. Servers can use this
to find the true sender of the e-mail, instead of assuming it's the value in
:mailheader:`From`. By default, this is ``noreply@<domain>``, but it can be
changed in the admin UI.

This still requires that the sender domain is configured properly for DKIM_
support.

See the :ref:`email` documentation for more information.

.. _DKIM: http://en.wikipedia.org/wiki/DomainKeys_Identified_Mail


New User Notifications
~~~~~~~~~~~~~~~~~~~~~~

Added support for e-mailing administrators when new users register.

Administrators can be notified when new users sign up on the Review Board
server. This is particularly useful for open source projects.

Patch by Hongbin Lu. (:bug:`1081`)


Repository Improvements
-----------------------

Private GitHub Organizations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Repository page in the administration UI now provides a Hosting Service
entry for private GitHub Organizations. This differs from the other GitHub
entries in that it requires the username used to access files on that
repository, rather than assuming the hosting owner account or organization
name is used.


Gitorious
~~~~~~~~~

Gitorious is now a supported hosting service for Review Board, and can be
easily configured on the Review Request page.

Patch by Hongbin Lu. (:bug:`2053`)


HTTP Basic Auth for Git
~~~~~~~~~~~~~~~~~~~~~~~

Added support for HTTP Basic Auth for Git repositories when using the
web-based raw file URL method.

Private git repositories requiring a username and password through the HTTP
Basic Auth mechanism can now be accessed from Review Board. The repository's
username and password are used when accessing the file requires authorization.


Perforce Stunnel
~~~~~~~~~~~~~~~~

Perforce repositories can be secured by using stunnel on the client and
server. Review Board now knows how to make use of this. A Perforce repository
path beginning with ``stunnel:`` will tell Review Board to use stunnel for all
communication to that repository.

See the :ref:`perforce-stunnel` documentation for more information.


Plastic SCM support
~~~~~~~~~~~~~~~~~~~

We support connecting to `Plastic SCM`_ repositories. Plastic SCM is a new SCM
provided by Codice Software. If you have a recent RBTools installed, it will
already work with Plastic SCM checkouts. Patch by Dick Porter.

.. _`Plastic SCM`: http://www.codicesoftware.com/


LDAP Improvements
-----------------

Added additional LDAP configuration for name attributes.

LDAP configurations can use different attributes to store people's names.
These attributes can now be customized in the LDAP configuration.

Patch by Tucker Dewitt. (:bug:`2122`)


Cache Setting
-------------

The cache backend can be changed through the Administration UI. Previously,
this needed to be modified in the :file:`conf/settings_local.py` file and
sometimes in the serialized settings in the database.

Patch by Vlad Filippov.


Troubleshooting
---------------

Review Board's Manual Updates pages have historically been a bit confusing,
and sometimes were misleading. They've now been completely replaced with
useful, detailed sets of instructions, along with any error messages that
would make debugging problems (broken database connections, for example)
easier.

It should be much easier now to get going after installing an existing Review
Board release, upgrading an old one, or when something goes wrong with the
database connection.


Extensibility
=============

Custom Authentication Backends
------------------------------

Custom authentication backends, if written against our new auth backend API
properly, will now show up automatically in the list of authentication
backends in Settings, much like LDAP, Active Directory, and others.

They can provide their own settings form, and save their settings in our
settings database. This makes it easier for companies and organizations to
write custom backends that tie into their services and to continue using them
release to release.

They can also specify capabilities, such as "is registration supported" or
"can names, e-mail addresses, or passwords be changed." For the latter, they
can also handle updating this information server-side when the user changes
it.

See `Writing Authentication Backends`_ for more information.

.. _`Writing Authentication Backends`:
   http://www.reviewboard.org/docs/codebase/dev/extending/auth-backends/


Performance Improvements
========================


Dashboard
---------

The dashboard is now much faster. We used to perform many queries (some that
were a bit slow) in order to get the counts for each section in the sidebar,
but now these counts are all cached. This provides a very noticeable speed
improvement, especially when using a lot of groups.


New Review Request Page
-----------------------

The New Review Request page generated far too many database queries when
displaying the list of repositories. It would query once per entry. With
hundreds of repositories, this would slow down the page and the server.

This has been drastically sped up and now performs much faster with large
lists.


Syntax Highlighting
-------------------

The rendering of syntax highlighting in diffs is now faster.

We switched to requiring Pygments_ 1.4, which offers speed improvements when
generating the syntax highlighting in our diffs. This upgrade also adds
support for new file types. The list can be found on their website.

.. _Pygments: http://www.pygments.org/


SCMTool Queries
---------------

Reduced queries when looking up SCMTools in the database.

We now cache lookups to SCMTools (the components responsible for talking to
repositories), reducing the amount of queries that need to be made on each
page.


Diff Viewer
-----------

Reduced the number of round trips to the database when loading the diff
viewer.

Patch by Ben Hollis.



API Changes
===========

* Added API for getting change descriptions.

  All the information from the change descriptions can now be retrieved.
  They contain more information than even the change descriptions on the
  website. Users, screenshots, and other such resource-backed data now
  embeds and links to the appropriate resource. (:bug:`2026`)

* Added a quick search API for retrieving basic searchable information.

  A ``/search/?q=`` resource has been added that can search for various
  bits of information based on search terms. It will search users
  (matching username, first name, and last name), groups (name and display
  name), and review requests (IDs and summaries).

  Patch by Crystal Lok Koo.

* Added a ``?ship-it=`` parameter to the review requests list resource.

  The ``/api/review-requests/`` API gained a ``?ship-it=`` filter that
  makes it easy to locate review request that either have a Ship It
  (if ``ship-it=1``), or have none (if ``ship-it=0``).

* Added support for HTTP caching headers for resources.

  Resources now provide and respect Last-Modified timestamps and ETags.
  Clients with HTTP caching header awareness will be able to tell if
  resources need to be fetched, or if the cached version will suffice.

  It's possible that there will be regressions on some resources that don't
  properly recompute their timestamps. If you encounter stale data, send
  us a bug report.

* Draft resources weren't always being fetched correctly, returning 404s.

* Fixed accessing diff resources for closed review requests. (:bug:`2009`)

  The diffs resource (and possibly others) was failing when accessed on
  a closed review request. It would return a 404 Not Found.

* Errors accessing Perforce repositories are now reported in the web API.


Removed Features
================

* The old 1.0 API has been removed. All clients need to be updated to use
  the new 1.5 API. If you're running a recent RBTools (post-review), you're
  fine.

* The old iPhone interface has been removed. The main UI works fine now
  with the iPhone and iPad.

* Removed RSS/Atom feed support.

  In the very early days, we had RSS/Atom feeds for review requests, users
  and groups. These aren't really useful anymore, and nothing has ever
  truly exposed them. Most likely, nobody even knows they exist. They're
  now gone.


Changes since 1.6 RC 2
======================

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

* Added a setting in the admin UI for setting the cache backend. Patch by
  Vlad Filippov.

* Added a new favorite icon, which works in Internet Explorer. Patch by
  Ben Allen.

* Added a :kbd:`Alt-I` shortcut for toggling the :guilabel:`Open an issue`
  checkbox in comment dialogs.

* The :guilabel:`Open an issue` checkbox is now checked by default.


Bug Fixes
---------

* Issue tracking now works with file attachment comments.

* Fixed some issues preventing database migrations from succeeding in rare
  cases.

* The e-mail address on the user info popup is now being shown again.

* The :guilabel:`Search Index File` setting has been renamed to
  :guilabel:`Search Index Directory` to better reflect how it's used.

* Fixed several issues with drag-and-drop on Chrome and Firefox causing
  flicker and stuck drop overlays. (:bug:`2196`)

* The manual updates page no longer fails on Windows if the necessary
  environment variables are missing. (:bug:`2214`)

* Duplicate draft comments and replies on the same review are no longer
  allowed through the API or UI. (:bug:`2154`)

* Replying to comments on file attachments has been fixed. (:bug:`2173`)

* Fixed dashboard counters when discarding or deleting draft review
  requests. (:bug:`2194`)

* Fixed a compatibility issue with Perforce on Python 2.4. (:bug:`2195`)

* Fixed password authentication on Perforce. (:bug:`2199`)


Contributors
============

* Alexander Solovets
* Ben Allen
* Ben Hollis
* Christian Hammond
* Colin Caughie
* Cristian Messel
* Crystal Lok Koo
* David Trowbridge
* Dick Porter
* Hongbin Lu
* Jan Koprowski
* Kevin Quinn
* Laila Agaev
* Mark Striemer
* Megan Schneider
* Mengyun Kong
* Mike Conley
* Paul Schulz
* Philipp Henkel
* Steve Sutcliffe
* Tucker Dewitt
* Vignesh Srinivasan
* Vlad Filippov


.. comment: vim: ft=rst et
