@title Differential User Guide
@group userguide
Guide to the Differential (pre-push code review) tool and workflow.
= Overview =
Phabricator supports two code review workflows, "review" (pre-push) and
"audit" (post-push). To understand the differences between the two, see
@{article:User Guide: Review vs Audit}.
This document summarizes the pre-push "review" workflow implemented by the tool
//Differential//.
= How Review Works =
Code review in Phabricator is a lightweight, asynchronous web-based process. If
you are familiar with GitHub, it is similar to how pull requests work:
- An author prepares a change to a codebase, then sends it for review. They
specify who they want to review it (additional users may be notified as
well, see below). The change itself is called a "Differential Revision".
- The reviewers receive an email asking them to review the change.
- The reviewers inspect the change and either discuss it, approve it, or
request changes (e.g., if they identify problems or bugs).
- In response to feedback, the author may update the change (e.g., fixing
the bugs or addressing the problems).
- Once everything is satisfied, some reviewer accepts the change and the
author pushes it to the upstream.
The Differential home screen shows two sets of revisions:
- **Action Required** is revisions you are the author of or a reviewer for,
which you need to review, revise, or push.
- **Waiting on Others** is revisions you are the author of or a reviewer for,
which someone else needs to review, revise, or push.
= Creating Revisions =
The preferred way to create revisions in Differential is with `arc`
(see @{article:Arcanist User Guide}). You can also create revisions from the
web interface, by navigating to Differential, pressing the "Create Revision"
button, and pasting a diff in.
= Herald Rules =
If you're interested in keeping track of changes to certain parts of a codebase
(e.g., maybe changes to a feature or changes in a certain language, or there's
just some intern who you don't trust) you can write a Herald rule to
automatically CC you on any revisions which match rules (like content, author,
files affected, etc.)
Inline Comments
===============
You can leave inline comments by clicking the line number next to a line. For
an in-depth look at inline comments, see
@{article:Differential User Guide: Inline Comments}.
Next Steps
==========
Continue by:
- diving into the details of inline comments in
@{article:Differential User Guide: Inline Comments}; or
- reading the FAQ at @{article:Differential User Guide: FAQ}; or
- learning about test plans in
@{article:Differential User Guide: Test Plans}; or
- learning more about Herald in @{article:Herald User Guide}.