[%#
  # The contents of this file are subject to the Mozilla Public
  # License Version 1.1 (the "License"); you may not use this file
  # except in compliance with the License. You may obtain a copy of
  # the License at http://www.mozilla.org/MPL/
  #
  # Software distributed under the License is distributed on an "AS
  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
  # implied. See the License for the specific language governing
  # rights and limitations under the License.
  #
  # The Original Code is the Splinter Bugzilla Extension.
  #
  # The Initial Developer of the Original Code is Red Hat, Inc.
  # Portions created by Red Hat, Inc. are Copyright (C) 2008
  # Red Hat, Inc. All Rights Reserved.
  #
  # Contributor(s): Owen Taylor <otaylor@redhat.com>
  #%]

[% PROCESS global/header.html.tmpl
  title = "Patch Review Help"
  header = "Patch Review Help"
%]

<h2>Splinter Patch Review</h2>
<p>
  Splinter is an add-on for [% terms.Bugzilla %] to allow conveniently
  reviewing patches that people have attached to
  [%+ terms.Bugzilla %]. <a href="http://fishsoup.net/software/splinter">More
  information about Splinter</a>.
</p>
<h3>The patch review view</h3>
<p>
  If you get to Splinter by clicking on a link next to an
  attachment in [% terms.Bugzilla %], you are presented with the patch
  review view. This view has a number of different pages that can
  be switched between with the links at the top of the screen.
  The first page is the Overview page, the other pages correspond to
  individual files changed by the review.
</p>
<p>
  On the Overview page, from top to bottom are shown:
</p>
<ul>
  <li>Introductory text to the patch. For a patch that was created
  using 'git format-patch' this will be the Git commit
  message.</li>
  <li>Controls for creating a new review</li>
  <li>Previous reviews that other people have written.</li>
</ul>
<p>
  The pages for each file show a two-column view of the changes.
  The left column is the previous contents of the file,
  the right column is the new contents of the file. (If the file
  is an entirely new file or an entirely deleted file, only one
  column will be shown.) Red indicates lines that have been
  removed, green lines that have been added, and blue lines that
  were modified.
</p>
<p>
  If people have previously made comments on individual lines of
  the patch, they will show up both summarized on the Overview
  page and also inline when looking at the files of the patch.
</p>
<h3>Reviewing an existing patch</h3>
<p>
  There are three components to a review:
</p>
<ul>
  <li>
    An overall comment. The text area on the first page allows
    you to enter your overall thoughts on the [% terms.bug %].
  </li>
  <li>
    Detailed comments on changes within the files. To comment on a
    line in a patch, double click on it, and a text area will open
    beneath that comment. When you are done, click the Save button
    to save your comment or the Cancel button to throw your
    comment away. You can double-click on a saved comment to start
    editing it again and make further changes.
  </li>
  <li>
    A change to the attachment status. (This is specific to
    [%+ terms.Bugzilla %] instances that have attachment status, which is a
    non-upstream patch. It's somewhat similar to attachment flags,
    which splinter doesn't currently support displaying or
    changing.) This allows you to mark a patch as read to commit
    or needing additional work. This is done by changing the
    drop-down next to the Publish button.
  </li>
</ul>
<p>
  Once you are done writing your review, go back to Overview page
  and click the "Publish" button to submit it as a comment on the
  [%+ terms.bug %]. The comment will have a link back to the review page so
  that people can see your comments with the full context.
</p>
<h3>Saved drafts</h3>
<p>
  Whenever you start making changes, a draft is automatically
  saved. If you come back to the patch review page for the same
  attachment, that draft will automatically be resumed. Drafts are
  not visible to anybody else until published.
</p>
<p>
  Note that saving drafts requires the your browser to have support
  for the "DOM Storage" standard. At time of writing, this is
  available only in a few very recent browsers, like Firefox
  3.5. Strict privacy protections like disabling cookies may also
  disable DOM Storage, since it provides another mechanism for
  sites to track information about their users.
</p>
<h3>Responding to someone's review</h3>
<p>
  A response is treated just like any other review and created the
  same way. A couple of features are helpful when responding: you
  can double-click on an inline comment to respond to it. And on
  the overview page, when you click on a detailed comment, you are
  taken directly to the original location of the comment.
</p>
<h3>Uploading patches for review</h3>
<p>
  Splinter doesn't really care how patches are provided to
  [%+ terms.Bugzilla %], as long as they are well-formatted patches. If you are
  using Git for version control, you can either format changes as
  patches
  using <a href="https://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html">'git
  format-patch</a> and attach them manually to the [% terms.bug %], or you
  can
  use <a href="http://fishsoup.net/software/git-bz">git-bz</a>.
  git-bz is highly recommended; it automates most of the steps
  that Splinter can't handle: it files new [% terms.bugs %], attaches updated
  attachments to existing [% terms.bugs %], and closes [% terms.bugs %] when you push the
  corresponding git commits to your central repository.
</p>
<h3>The [% terms.bug %] review view</h3>
<p>
  Splinter also has a view where it shows all patches attached to
  the [% terms.bug %] with their status and links to review them. You are
  taken to this page after publishing a review. You can also get
  to this page with the [% terms.bug %] link in the upper-right corner of the
  patch review view.
</p>
<h3>Your reviews</h3>
<p>
  Splinter can also show you a list of all your draft and
  published reviews. Access this page with the "Your reviews"
  link at the bottom of the [% terms.bug %] review view. In-progress drafts
  are shown in bold.
</p>

[% PROCESS global/footer.html.tmpl %]
