[Summary view] [Print] [Text view]

   1  @title Differential User Guide
   2  @group userguide
   3  
   4  Guide to the Differential (pre-push code review) tool and workflow.
   5  
   6  = Overview =
   7  
   8  Phabricator supports two code review workflows, "review" (pre-push) and
   9  "audit" (post-push). To understand the differences between the two, see
  10  @{article:User Guide: Review vs Audit}.
  11  
  12  This document summarizes the pre-push "review" workflow implemented by the tool
  13  //Differential//.
  14  
  15  = How Review Works =
  16  
  17  Code review in Phabricator is a lightweight, asynchronous web-based process. If
  18  you are familiar with GitHub, it is similar to how pull requests work:
  19  
  20    - An author prepares a change to a codebase, then sends it for review. They
  21      specify who they want to review it (additional users may be notified as
  22      well, see below). The change itself is called a "Differential Revision".
  23    - The reviewers receive an email asking them to review the change.
  24    - The reviewers inspect the change and either discuss it, approve it, or
  25      request changes (e.g., if they identify problems or bugs).
  26    - In response to feedback, the author may update the change (e.g., fixing
  27      the bugs or addressing the problems).
  28    - Once everything is satisfied, some reviewer accepts the change and the
  29      author pushes it to the upstream.
  30  
  31  The Differential home screen shows two sets of revisions:
  32  
  33    - **Action Required** is revisions you are the author of or a reviewer for,
  34      which you need to review, revise, or push.
  35    - **Waiting on Others** is revisions you are the author of or a reviewer for,
  36      which someone else needs to review, revise, or push.
  37  
  38  = Creating Revisions =
  39  
  40  The preferred way to create revisions in Differential is with `arc`
  41  (see @{article:Arcanist User Guide}). You can also create revisions from the
  42  web interface, by navigating to Differential, pressing the "Create Revision"
  43  button, and pasting a diff in.
  44  
  45  = Herald Rules =
  46  
  47  If you're interested in keeping track of changes to certain parts of a codebase
  48  (e.g., maybe changes to a feature or changes in a certain language, or there's
  49  just some intern who you don't trust) you can write a Herald rule to
  50  automatically CC you on any revisions which match rules (like content, author,
  51  files affected, etc.)
  52  
  53  = Differential Tips =
  54  
  55    - You can leave inline comments by clicking the line numbers in the diff.
  56    - You can leave a comment across multiple lines by dragging across the line
  57      numbers.
  58    - Inline comments are initially saved as drafts. They are not submitted until
  59      you submit a comment at the bottom of the page.
  60    - Press "?" to view keyboard shortcuts.
  61  
  62  = Next Steps =
  63  
  64    - Read the FAQ at @{article:Differential User Guide: FAQ}; or
  65    - learn about handling large changesets at
  66      @{article:Differential User Guide: Large Changes}; or
  67    - learn about test plans at @{article:Differential User Guide: Test Plans}; or
  68    - learn more about Herald at @{article:Herald User Guide}; or
  69    - give us feedback at @{article:Give Feedback! Get Support!}.