.. _creating-review-requests:

========================
Creating Review Requests
========================

A review request consists of, at a minimum, a summary, a description, and some
reviewers. A review request usually has a diff, but it can be useful to have
review requests that only have file attachments.

There are two main ways of submitting a new review request: through the
web UI and through :ref:`post-review`. We recommend the latter when posting
diffs for review, as it does a lot of work for you, and is actually required
for some version control systems, such as Perforce.


Web UI
======

To post a review request through the web UI, click
:guilabel:`New Review Request` in the upper-left of a page. This will take
you to a form where you can create your review request. What information you
provide depends on whether you're posting a diff for review, or intending to
post file attachments for review.

Once you've filled out all fields, click :guilabel:`Submit` to post the
review request.


.. _review-requests-for-diffs:

Review Requests for Diffs
-------------------------

If you're uploading a diff, you will need to select a repository and browse
to the diff you wish to upload.

The diff you provide needs to be in :term:`unified diff` format, and must
have revision information embedded in the file. CVS, Subversion, Git,
Mercurial and Bazaar provide this information. If you use Perforce,
though, you'll need to use :ref:`post-review` instead of the web UI. Note
that this means you can't just use a standard diff generated by the
:command:`diff` tool. You'll need to consult your version control system's
documentation for information on generating diffs.

Once you've generated the diff, specify it in the form. You'll also need to
specify the repository containing the code that the diff was generated
against. On many Review Board installations, you'll only have one choice, but
some may have multiple ones to choose from.

.. image:: new-review-request-form.png

After selecting the repository, additional fields dependent on that repository
may become available. Here are some fields you may encounter.

**Perforce repositories:**

* :guilabel:`Change Number`:

  The changeset number representing the change the diff is generated from.

**Subversion repositories:**

* :guilabel:`Base Directory`:

  The relative path of the directory you were in when you generated the diff,
  based on the repository. For example, if you locally have a checkout of
  :file:`trunk/reviewboard` named :file:`reviewboard`, and that was the
  directory you were in when you made the diff, then the base diff path would
  be ``/trunk/reviewboard``.

  This may also depend on how Review Board was configured. Consult your
  administrator if you have problems.


Review Requests for File Attachments Only
-----------------------------------------

If you're intending to post a review request only for reviewing file
attachments, you will want to change the :guilabel:`Repository` to
:guilabel:`(None - File Attachments only)`. You will not be able to add any
diffs to this review request, but after creating it, you will be able to add
attachments.

No other fields will need to be provided when using this option.


Finishing the Review Request
============================

Once you've posted your initial diff through the web UI or :ref:`post-review`,
you'll have a draft of your review request posted. Nobody but you will be
able to see the review request until you publish it.

Before you publish the review request, you'll need to fill out the summary,
description and reviewers. Some of these fields may be filled in depending
on your repository type, the tool you used to post the review request, and
any defaults your administrator has set up for the reviewers (see
:ref:`managing-default-reviewers` if you're the administrator).

File attachments can be added with the :menuselection:`Update --> Add File` menu
item or by dragging and dropping files onto the page in the browser.

You can preview your diff by clicking :guilabel:`View Diff` in the review
request action bar (in the top-right of the review request). Uploading a new
diff (either using the :menuselection:`Update --> Update Diff` menu item or with
:ref:`post-review`) before publishing will replace the diff.

When you're finished, click :guilabel:`Publish Review Request` in the green
draft banner above the review request. You can also choose to discard the
review request by clicking :guilabel:`Discard`.

Depending on your particular setup, publishing a review request may send
an e-mail out to the reviewers, letting them know your change is ready to
review.


.. comment: vim: ft=rst et ts=3
