=====================================
Review Board 3.0 Beta 1 Release Notes
=====================================

**Release date**: March 29, 2017


This release contains all bug fixes and features from Review Board version
:doc:`2.5.9 <2.5.9>`.


Installation
============

To install this release, run the following::

    $ sudo pip install \
        --trusted-host downloads.reviewboard.org \
        -f http://downloads.reviewboard.org/releases/Djblets/0.10/ \
        -f http://downloads.reviewboard.org/releases/ReviewBoard/3.0/ \
        -f http://downloads.reviewboard.org/releases/rbintegrations/0.5/ \
        --pre -U ReviewBoard

Or::

    $ sudo easy_install \
        -f http://downloads.reviewboard.org/releases/Djblets/0.10/ \
        -f http://downloads.reviewboard.org/releases/ReviewBoard/3.0/ \
        -f http://downloads.reviewboard.org/releases/rbintegrations/0.5/ \
        -U ReviewBoard

We **do not** recommend upgrading a production server with this version of
Review Board. It's best to install on a test server, with a copy of your
production database, in case there are any major problems.


Upgrade Notes
=============

This release contains database schema changes to the following tables:

* ``accounts_profile``
* ``attachments_fileattachment``
* ``changedescs_changedescription``
* ``reviews_reviewrequestdraft``
* ``reviews_review``
* ``scmtools_repository``
* ``site_localsite``

This will take some time to migrate the database, particularly on large
installs. Please test the upgrade on a copy of your database first, to ensure
the upgrade is smooth and to time how long the upgrade takes.

Do **not** cancel the upgrade on a production system for any reason.


Compatibility Changes
=====================

* In Review Board 3.0, we've made some significant changes and cleanups to the
  HTML markup and CSS for the main review request page. If you've created an
  extension that uses ID or class selectors, or a user stylesheet, you'll need
  to update it for those changes. The exact changes have been documented `on
  our wiki
  <https://www.notion.so/reviewboard/Review-Request-page-changes-for-3-0-8d27aac9e3ed4f81ac1e849ebb6127fe>`_.

* Review Board 3.0 requires Python 2.7 or higher.


New Features
============

General Comments
----------------

Review Board has traditionally supported comments on actual content, such as
lines of code or file attachments. It's common to also want to make more
general comments on a review request as a whole (for example, if a major
refactor is required, it probably doesn't make sense to add that comment on an
individual line of code). Users have traditionally used the review header
and/or footer for these, but that did not allow tracking issues.

You can now click :guilabel:`Add Comment` in the review request or review edit
dialog to add a general comment, including opening an issue.

Based on work by Yanjia Xin.


Integrations
------------

* Added new support for configuring third-party service integrations for Review
  Board.

  Review Board can now work more closely with other third-party services, such
  as chat services (Slack, HipChat), task trackers (Asana, Trello), continuous
  integration services (Travis CI, CircleCI), and more through the new
  Integrations framework. As of beta 1, we only offer Slack support out of the
  box, but more will ship by the final 3.0 release.

  Integrations are registered by extensions, but unlike an extension, an
  integration can have any number of different configurations active at once.
  That means that, for instance, multiple teams at a company could each have
  their own unique Slack configurations that notify their own channels when
  review requests are posted to their groups, or could have their own build
  configurations for Travis CI.

  Official Review Board integrations are provided by the rbintegrations Python
  package, which will be updated independently of Review Board, allowing us to
  ship updates to extensions to you without having to upgrade Review Board. The
  latest supported version of this package is automatically installed when
  installing or upgrading Review Board.

* Slack integration.

  Review Board can now notify one or more channels on `Slack`_ when review
  requests and reviews are published. This is configured through the
  integration configurations.

.. _Slack: https://slack.com/


Status Updates
--------------

Status Updates are a new feature which make it easy for third-party tools to
provide some kind of status and feedback on a review request. One example of a
tool like this is `Review Bot`_, which automatically runs static analysis tools
against posted code changes. Until now, the results of this were posted as a
regular review, and there was no feedback visible until that review was posted
(for example, there was no way to tell if the tool was running or if it had
crashed).

With a status update, each tool can mark a status on a change, such as
"pending", "success", or "failure". These can be attached to either the review
request as a whole, or to an individual change description. Reviews can be
associated with these, which allows those tools to add comments and open
issues.

A forthcoming release of Review Bot will add support for posting the results
using the status updates feature.

Based on work by Shuai Shao.

.. _`Review Bot`: https://github.com/reviewboard/ReviewBot/


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

* Reassign Review Request ownership.

  The ownership of a review request can now be changed by either the review
  request's current owner (i.e. the submitter) or an administrator. This allows
  review requests to be transferred from one user to another if they've been
  abandoned or the work has been handed off.

  For users who have the right permission, the :guilabel:`Submitter` field
  under a review request's :guilabel:`Information` section can now be edited.
  If a regular user is making the change, they can give away ownership but
  cannot reclaim it later (that is, it must be reassigned back by the new
  owner).

  Patch by Chenxi Ni.

* Auto-complete for the "Depends On" field.

  When adding items to the "Depends On" field in a review request, you can now
  type in review request numbers or text from the summary field and
  auto-complete the results.

  Patch by Connor Yoshimoto.


Reviews
-------

* Send review only to submitter.

  In large teams, the amount of e-mail traffic generated by code reviews can be
  significant. Sometimes, the contents of a code review can be trivial or
  direct enough that it's really not worth notifying everybody about the
  change. In this case, you can now select to publish the review :guilabel:`to
  Submitter Only`. This will still show up in the web UI and update on people's
  dashboards, but the e-mail will only be sent to the author of the change.

* Delete comments from the "Edit Review" dialog.

  The review dialog now displays a delete icon next to the edit icon for each
  comment. This allows diff comments, file attachment comments, and general
  comments to be removed without finding the original comment flag or
  discarding the entire review.

* Drag-and-drop images into text fields.

  When using Markdown in text fields (such as the review request description or
  comment text), you can now drag-and-drop an image file into the text box
  (while in edit mode) to upload it and show it inline with your text. This
  allows easy sharing of mock-ups or annotations within your discussions.

  Based on work by David Kus.


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

* View the content of deleted files.

  Deleted files have typically just been listed as deleted with the content
  hidden. You can now choose to see the content of these files.

  Patch by Adriano Arce.

* Improved display for patch errors.

  If a patch fails to apply correctly (either due to a bad patch or a problem
  with the configured repository), Review Board would show a pretty terrible
  error message and leave debugging files in a temporary directory on the
  server which was only accessible by the administrator. Review Board will now
  allow you to view the rejects inline, and makes it easy to download a bundle
  containing the original file, patch file, and the rejects.

  Based on work by Tien Vu.


File Attachment Review
----------------------

* Cycle through file attachments.

  When reviewing multiple file attachments, it's common to go through every
  attached file in turn. Doing so was kind of annoying because it required
  navigating back to the main review request page (or opening every attachment
  in a different tab).

  We've now added "next" and "previous" attachment buttons on the file
  attachment view. These ordinarily keep out of the way, but will slide out
  from the left or right when hovered over with the mouse.

* Zoom in and out when reviewing images.

  With the advent of high-DPI screens, it's common for screenshots or image
  assets to have a 2x or 3x ratio between display pixels and virtual pixels.
  In order to facilitate review of these files, the image review UI now allows
  selecting a zoom level (either 33.3%, 50%, 100%, or 200%). These presets
  allow easily viewing 2x or 3x assets at their natural size.

  If the image attachment filename includes "@2x" or "@3x", the correct zoom
  level will be preselected when opening the file. Otherwise, the image will be
  zoomed such that it attempts to fit within the browser window.

* Scroll oversized images.

  When reviewing very large image file attachments (such as whole-screen
  screenshots), they would previously overflow the bounds of the containing
  box. These will now be contained entirely within the review box and can be
  scrolled.


Administration Features
-----------------------

* Support for Splat as a bug tracker.

  Splat is a new bug tracker service we currently have in development, designed
  to be flexible in its usage and to tie into other project management tools.
  It's being used to track bugs and features for Review Board, and will in time
  be available for others to use.

* Support for Elasticsearch as a search backend.

  You can now choose between Whoosh (the default) and Elasticsearch backends
  for the full-text search functionality.

* Optionally send an e-mail when a user's password has changed.

  The administator can now configure Review Board to notify users via e-mail if
  their password has been changed. This defaults to disabled.

* Opt-in feature checks.

  Beta 1 lays the groundwork for a new "feature check" system, which we'll be
  using going forward to help test experimental new features. Feature checks
  allow us to produce new features or to change existing features without
  impacting existing installations. Administrators who want to help test these
  changes will be able to opt in to the features, and opt back out if they
  introduce problems.

  Extension authors can also make use of the feature system to help test new
  experimental support in production without affecting all the users on a
  system or requiring a test server to be set up.

  As of beta 1, there aren't currently any opt-in features in Review Board
  itself. Future releases will begin to introduce new opt-in features.

* New Bazaar backend.

  We've rewritten the Bazaar support to use the command line tool, improving
  compatibility and ensuring we stay license-compliant. The 2.0.x and 2.5.x
  release series will be receiving this fix soon.


Other New Features
------------------

* New user infobox design.

  The box that appears when hovering the mouse over a user's name in throughout
  the application has been redesigned and expanded with more information.

* New avatar backends.

  Until now, user avatars were provided by the Gravatar_ service. This could be
  disabled entirely by the server administrator, but there was no way to enable
  the use of avatars from another source.

  Review Board now supports multiple avatar backends. By default, two backends
  are available for every user: the existing Gravatar_ backend, and a new one
  that allows users to upload an image file.

  Backends can also be provided by extensions. This is useful if you have some
  centralized system for photos which you'd like to integrate with.

* Review Request metadata for social media sites and chat services.

  Services like Facebook, Twitter, Slack, and others can make use of metadata
  on a page to show a more useful preview. Review Board now includes this
  metadata on review requests.

* Support for desktop notifications.

  Review Board can now pop up notifications on your desktop when a review
  request is open in the browser. This can be enabled in the user account
  settings.

  Patch by Kristina Vandergulik.

* Added a "Show inactive" toggle to the users list page.

  The users grid now allows toggling to show or hide inactive users.

  Patch by Raman Dhatt.

.. _Gravatar: https://en.gravatar.com/
.. _Splat: https://hellosplat.com/


Extensions
==========

* Extensible user infobox.

  Extensions can now add information to the box which pops up when hovering the
  mouse over a user's name.

* Private ``extra_data`` fields.

  Many objects in the database provide an ``extra_data`` field, which is useful
  for extensions and API users to store additional information associated with
  that object. Until now, everything within this field was exposed via the API.
  Keys starting with a double underscore (``__``) will now be hidden from the
  API, allowing extensions to store semi-private information.

* Extensible review request actions.

  The actions at the upper right of a review request (such as the items in the
  :guilabel:`Close` and :guilabel:`Update` menus, or the :guilabel:`Review`
  command) can now be extended by using :ref:`rb3.0:action-hook`.

  Patch by Adriano Arce.


Web API
=======

* Allow users with the ``submit_as`` permission to see unpublished review
  requests.

  If users are allowed to submit or update review requests on behalf of other
  users, they were not able to use :command:`rbt post -u` to update review
  requests which had not yet been made public. Previously, only administrators
  could list unpublished review requests.

  Patch by Halvor Lund.

* Added an ``absolute_url`` field to the
  :ref:`rb3.0:webapi2.0-review-resource` payload.

  This field contains the URL to view the review within the web UI.


Bug Fixes
=========

* Updated Bitbucket support to use the version 2.0 API.

  Occasionally, Bitbucket repositories would encounter unexplained errors and
  outages, due to some bugs and incompatibilities on Bitbucket's side. We've
  switched over to their 2.0 API, which should improve stability.

* Fixed confirm dialogs before leaving the page when there's unsaved work.
  (:bug:`4084`)

  In some cases, leaving the page when there were unsaved comments as part of a
  review would fail to prompt the user.

  Patch by Kanghee Park.

* Fixed blank "Files" list when loading a review request. (:bug:`4468`)

  When initially loading a review request that has file attachments, the
  "Files:" label would appear with a blank box below it, and then the file
  attachments would appear after a short wait. We've added a loading indicator
  so it looks less broken.

  Patch by Anni Cao.

* Fixed the order of captions within the image review UI.

  When reviewing a diff between two revisions of an image, if the revisions had
  different captions, those captions would be shown in the wrong order.

* Fixed the display of "pop up" pages in the admin UI.

  The database section of the admin UI occasionally pops up a new window, to
  select or create related objects. These pages were intended to be simple
  content, but they included the header and sidebar. This has been fixed.

* Fixed a bug saving a group when there are inactive users who are members.
  (:bug:`4513`)

  Review Board 2.5.8 introduced a regression where trying to save an existing
  review group that had members who had since been marked as "inactive". This
  fix is included here, but will also ship in version 2.5.10.

* Fixed intermittent compatibility issues with Mercurial and Python versions.

  In some setups, executing the `hg` application would cause errors or failures
  due to mismatched python versions.

* Fixed several problems relating to move detection. (:bug:`4371`)

  There were a variety of small problems with move detection in diffs that have
  been addressed.

* Fixed a bug where expanding sections in the diff viewer would duplicate the
  "whitespace changes only" banner. (:bug:`4422`)


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

* Adriano Arce
* André Klitzing
* Anni Cao
* Barret Rennie
* Chenxi Ni
* Christian Hammond
* Connor Yoshimoto
* David Kus
* David Trowbridge
* Erik Johansson
* Griffin Myers
* Halvor Lund
* Jean Hominal
* Kanghee Park
* Kristina Vandergulik
* Mike Conley
* Orjan Monsen
* Raman Dhatt
* Sharleen Fisher
* Shuai Shao
* Tien Vu
* Yanjia Xin
