.. default-intersphinx:: djblets2.0 rb4.0

=====================================
Review Board 4.0 Beta 1 Release Notes
=====================================

**Release date**: December 16, 2020


Review Board 4.0 beta 1 is the first release to support Python 3 (versions
3.6 through 3.9), and the 4.x series will be the last to support Python 2.7.

If you're giving this a try, we recommend installing using a recent version
of Python 3.

This release contains all bug fixes and features from Review Board version
3.0.19.


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

To install this release, run the following::

    $ sudo pip install \
        --trusted-host downloads.reviewboard.org \
        -f http://downloads.reviewboard.org/releases/ReviewBoard/4.0/ \
        -f http://downloads.reviewboard.org/releases/rbintegrations/2.0/ \
        --pre -U ReviewBoard

Or::

    $ sudo easy_install \
        -f http://downloads.reviewboard.org/releases/ReviewBoard/4.0/ \
        -f http://downloads.reviewboard.org/releases/rbintegrations/2.0/ \
        -U ReviewBoard


.. note::

   If this is a new install, please use :command:`pip`, as support for
   :command:`easy_install` is going away.


.. warning::

   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:

  * ``diffviewer_diffset``
  * ``diffviewer_filediff``

  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.

  .. important::

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

* We have a new process for applying database upgrades.

  This should be mostly behind-the-scenes, but please let us know if you
  hit any issues with upgrading.

* Your :file:`conf/reviewboard.wsgi` (or custom WSGI script) might need to be
  updated!

  :command:`rb-site upgrade` will try to update this automatically, but you
  might need to make the changes yourself if your setup is more specialized:

  .. code-block:: python

     # If you see these lines:
     import django.core.handlers.wsgi
     application = django.core.handlers.wsgi.WSGIHandler()

     # Change them to:
     from django.core.wsgi import get_wsgi_application
     application = get_wsgi_application()


Packaging
=========

* Review Board 4.0 supports Python 2.7 and 3.6-3.9.

* :pypi:`Django` 1.11.x is required.

* :pypi:`Djblets` 2.0 is required.

* :pypi:`django_evolution` 2.x (2.1 or higher) is required.

* :pypi:`django-haystack` 2.x (2.7 or higher) is required.

* :pypi:`markdown` 3.1.x (3.3.1 or higher) is required on Python 2.7, and
  3.3.3 or higher on Python 3.

* :pypi:`pymdown-extensions` 6.x (6.2 or higher) is required on Python 2.7,
  and 6.x (6.3 or higher) on Python 3.

* :pypi:`Pygments` 2.1 or higher is required (2.5.x is the latest supported
  version on Python 2.7).


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

Multi-Commit Review Requests
----------------------------

Review Board was first created in an era of centralized revision control,
where a single patch corresponded to a single commit. Since then, the world
has moved on, and it's not uncommon to develop on branches where multiple
commits all contribute to a single development task. While it was possible to
review these in various ways using RBTools to post either ranges or individual
commits, it wasn't the ideal experience.

We're proud to introduce true multi-commit support for Review Board. Each
revision of the diff in a Review Request can now contain multiple commits
which can be viewed and commented on, either individually or in ranges.

This is supported for Git and Mercurial repositories, and requires
RBTools_ 2.0 or higher to post the changes.


.. _RBTools: https://www.reviewboard.org/downloads/rbtools/


Installation and Setup
----------------------

* Better guidance for site creation.

  When installing a new Review Board site, :command:`rb-site` now uses
  visual hints (colors and improved layout of text) to help you through your
  installation.

  You can disable color by passing :option:`--no-color`.

* Simpler installation of optional Python dependencies.

  Installation of optional dependencies has been simplified. The following
  Python support modules can now be installed through :command:`pip`:

  * Mercurial: ``pip install -U ReviewBoard[mercurial]``
  * Postgres: ``pip install -U ReviewBoard[postgres]``
  * Subvertpy: ``pip install -U ReviewBoard[subvertpy]``
  * MySQL: ``pip install -U ReviewBoard[mysql]``
  * Perforce: ``pip install -U ReviewBoard[p4]``
  * LDAP: ``pip install -U ReviewBoard[ldap]``
  * S3 File Storage: ``pip install -U ReviewBoard[s3]``
  * OpenStack Swift File Storage: ``pip install -U ReviewBoard[swift]``


New Integrations
----------------

* :rbintegration:`Discord <discord>`

  Discord is a chat system similar to Slack, but with a focus on communities,
  from open source to gaming to general discussions.

  Review Board can now post to Discord when review requests are posted or
  updated, or whenever there's new discussions on the review request.

  See the :ref:`documentation <integrations-discord>` for configuration
  instructions.

  Patch by Hailan Xu.

* :rbintegration:`Jenkins <jenkins>`

  Jenkins is a widely-used continuous integration, deployment, and automation
  service. It's open source, self-hosted, and extensible with plugin support.

  This integration works along with a Review Board plugin for Jenkins to
  trigger builds when a review request is posted or updated.

  See the :ref:`documentation <integrations-jenkins-ci>` for configuration
  instructions.

  Patches by James Shephard and Marcus Boay.


User Features
-------------

* Added an "Overview" section in the Dashboard (:bug:`750`).

  Until now, the dashboard has has :guilabel:`Outgoing` and
  :guilabel:`Incoming` sections, which list the review requests owned by a user
  and the review requests assigned to a user (directly or as part of a group),
  respectively.

  The new :guilabel:`Overview` section can be thought of as a union of those
  two, showing all open incoming and outgoing review requests.

  Patch by Bolarinwa Balogun.

* Quickly archive review requests by clicking on the inbox icon.

  The inbox icon in the actions bar of a review request shows a menu containing
  :guilabel:`Archive` and :guilabel:`Mute` options. It's often annoying to wait
  for that menu to apper, so clicking on the icon itself will now trigger the
  archive/unarchive action.

  Patch by Malcolm Gomes.

* Added "Publish and Archive" to the review dialog and banner.

  It's common to immediately archive a review request after publishing a
  review. The drop-down on the Publish button in the review dialog and banner
  now includes an option to publish and archive the review request with a
  single click.

  Patch by Guilia Mattia.

* Added live thumbnails for video files.

  Hovering over a video file will now load the video and play a short
  segment of it, to give you a sense of the content.


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

* Introducing a new administration UI.

  We've rewritten the administration UI to provide a cleaner look with
  a focus on mobile support. This fits in better with the general look and
  field of Review Board, and shares many of the components found throughout
  the rest of the product.

  Navigation is no longer split between a sidebar and a banner at the top.
  You now navigate solely through the sidebar. On mobile, navigation appears
  in the standard mobile menu.

* Read-only mode.

  Administrators can now put the site into read-only mode, which will be shown
  to all users accessing Review Board. This is intended for use when
  performing maintenance or upgrades on the server, preventing users from
  submitting data which might be lost during the process.

  This does not prevent all writes to the database (administrators can still
  make changes), but provides a good mechanism for preventing users from
  losing their work.

  Patch by Kanghee Park.

* Added new smarter object selectors for repositories and groups.

  Review Board 2.5.7 introduced a new selector for choosing users which avoided
  some of the performance issues that could arise with the default Django
  related-object selectors. This new selector UI is now also used for choosing
  related groups and repositories.

  Patch by Storm Kaefer.


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

* Added hints to avoid search bot indexing for many links.

  If your server is public, you likely have search engine bots constantly
  crawling every review request, diff revision, interdiff range, and
  page of results in the dashboard, which can slow down a server.

  To avoid that, we've added ``rel="nofollow"`` attributes to many links
  throughout the web UI.


Web API
=======

* Added new APIs and fields for multi-commit review requests:

  * :ref:`webapi2.0-validate-diff-commit-resource`

  * :ref:`webapi2.0-diff-commit-resource`

  * ``created_with_history`` field on :ref:`webapi2.0-review-request-resource`
    payloads

  * ``create_with_history`` field when creating a
    :ref:`webapi2.0-review-request-resource`

  * ``commit_count`` field on :ref:`webapi2.0-diff-resource` payloads


* :ref:`webapi2.0-review-resource` now accepts a ``publish_and_archive``
  boolean field to archive the review after publish.

* :ref:`webapi2.0-repository-resource` can now filter repositories that start
  with a particular prefix by passing ``?q=...`` in the request.

* Fixed :http:`500` errors from
  :ref:`webapi2.0-review-general-comment-resource` when the user did not have
  access permissions.


Extensions
==========

.. note::

   Extensions must be updated to support Django 1.11 and Python 3!

   This may require a lot of work on your part, depending on the complexity
   of your extension. See our `guide on upgrading to Django 1.11
   <https://www.notion.so/reviewboard/Upgrading-from-Django-1-6-to-1-11-6141bf5e7e684332820c2eab9a16d434>`_ for help, or reach out to us for support_.

.. _support: https://www.reviewboard.org/support/

* Added new standard CSS classes for forms, buttons, spinners, sidebars,
  and more.

  You can make use of these in your own code to help your extension better
  fit in with Review Board.

  We don't have any HTML documentation for this at this point, but you can
  find in-code documentation for the following:

  * :rbsrc-4.0.x:`Standard colors <reviewboard/static/rb/css/ui/colors.less>`
  * :rbsrc-4.0.x:`Admin UI dashboard widgets
    <reviewboard/static/rb/css/ui/admin/widgets.less>`
  * :rbsrc-4.0.x:`Alert boxes <reviewboard/static/rb/css/ui/alert.less>`
  * :rbsrc-4.0.x:`Buttons, button groups, and menu buttons
    <reviewboard/static/rb/css/ui/buttons.less>`
  * :rbsrc-4.0.x:`Decorative boxes <reviewboard/static/rb/css/ui/boxes.less>`
  * :rbsrc-4.0.x:`Drop-down menus <reviewboard/static/rb/css/ui/menus.less>`
  * :rbsrc-4.0.x:`Forms <reviewboard/static/rb/css/ui/forms.less>`
  * :rbsrc-4.0.x:`Main page content boxes
    <reviewboard/static/rb/css/ui/page-content-box.less>`
  * :rbsrc-4.0.x:`Main page content headers
    <reviewboard/static/rb/css/ui/content-header.less>`
  * :rbsrc-4.0.x:`Main page sidebars
    <reviewboard/static/rb/css/ui/page-sidebar.less>`
  * :djbletssrc-2.0.x:`My Account configuration forms
    <djblets/static/djblets/css/config-forms.less>`
  * :rbsrc-4.0.x:`Search fields
    <reviewboard/static/rb/css/ui/search-field.less>`
  * :rbsrc-4.0.x:`Sidebars <reviewboard/static/rb/css/ui/sidebars.less>`
  * :rbsrc-4.0.x:`Slide-out drawers
    <reviewboard/static/rb/css/ui/drawer.less>`
  * :djbletssrc-2.0.x:`Spinners <djblets/static/djblets/css/ui/spinner.less>`
  * :rbsrc-4.0.x:`Tabs <reviewboard/static/rb/css/ui/tabs.less>`
  * :rbsrc-4.0.x:`Tabular data for review request fields
    <reviewboard/static/rb/css/ui/review-request/fields/tabular.less>`

* Added new template blocks for defining extension-provided page classes,
  attributes, and options.

  Custom pages created by extensions should now override the following blocks:

  * ``js-page-view-type``: The name of the JavaScript :js:class:`RB.PageView`
    subclass managing the page's rendering.
  * ``js-page-view-options``: Options to pass to the :js:class:`RB.PageView`
    subclass's ``options`` parameter.
  * ``js-page-model-type``: The name of the JavaScript :js:class:`RB.Page`
    subclass managing the page's state.
  * ``js-page-model-options``: Options to pass to the :js:class:`RB.PageView`
    subclass's ``options`` parameter.
  * ``js-page-model-attrs``: Attributes to set on the :js:class:`RB.Page`.
    subclass.

* Extensions can define global variables for templates in a new
  ``global-vars`` template block.

  This allows you to define a variable once in a common place and use it
  in any other template block. For example:

  .. code-block:: django

     {% load djblets_utils %}

     {% block global-vars %}
     {%  definevar "my_variable" %}value...{% enddefinevar %}
     {% endblock global-vars %}

     {% block content %}
     {{my_variable}}
     {% endblock %}

* Custom JavaScript can now access :js:class:`RB.Product` to determine
  the Review Board version, release status, and manual URL.


Bug Fixes
=========

Dashboard
---------

* Fixed :http:`404` errors when changing datagrid filters (:bug:`4653`).

  If the dashboard filters were changed while viewing a page other than the
  first (for example, going from archived review requests being shown to being
  hidden), the new total number of results may not have as many pages. This
  could result in the display of a 404 page instead of the results. The
  datagrid will now reset to viewing the first page when changing filters.

  Patch by Mandeep Singh.


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

* Rewrote the interdiff algorithm to address numerous edge cases.

  Review Board 3.x users on occasion noticed problems with missing lines in
  interdiffs, due to some bad assumptions made by the old algorithm. We've
  rewritten the algorithm to correct these.

  Please give this a test and report any interdiff issues to us, so that we
  can correct them before 4.0 is released.


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

* Fixed creating draft review requests when using :guilabel:`Update > Add
  Files` (:bug:`4760`).

  Using drag-and-drop to attach a file attachment to a review request without
  an active draft would correctly create a draft, but this was not happening
  correctly when using the :guilabel:`Add File` action.

  Patch by Sarah Hoven.


Review UIs
----------

* Added ``application/x-javascript`` matching for the text Review UI.

  Many browsers are now referring to JavaScript files using the
  ``application/x-javascript`` MIME type (rather than the traditional
  ``text/javascript``). This was preventing JavaScript file attachments from
  being reviewable.

* Tightened up MIME type matching to prevent over-eager assignment of Review
  UIs.

  Different user interfaces for file review are assigned based on MIME type,
  but the matching was too loose, especially for types starting in
  ``application/``. This could result in the wrong review UI being shown (for
  example, a text file UI shown for a PDF attachment).


Administration
--------------

* Fixed handling of error conditions in the ``loaddb`` management command
  (:bug:`4629`).

  Patch by Jeremie Corriveau.


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

This is a big release, with improvements, bug fixes, and polish from a large
number of contributors. Thank you for all your work on 4.0!

* Adil Malik
* André Klitzing
* Barret Rennie
* Bolarinwa Balogun
* Christian Hammond
* David Trowbridge
* Giulia Mattia
* Griffin Myers
* Hailan Xu
* Hannah Lin
* James Shephard
* Jeremie Corriveau
* Kanghee Park
* Malcolm Gomes
* Mandeep Singh
* Marcus Boay
* Mike Conley
* Nicole Hagerman
* Ruonan Jia
* Sarah Hoven
* Storm Kaefer
* Xiaohui Liu
