mirror of
https://we.phorge.it/source/phorge.git
synced 2025-01-22 12:41:19 +01:00
536b0867de
Summary: Ref T988. I'm splitting the Phabricator documentation into two separate documentation books, one less technical and one more technical. Move all the `.diviner` article files around into `src/docs/user/` or `src/docs/tech/`, accordingly. The only actual changes here are a couple of config changes in the `.book` files. Test Plan: Regenerated user and technical documentation and saw stuff in the right places. Reviewers: btrahan Reviewed By: btrahan CC: chad, aran Maniphest Tasks: T988 Differential Revision: https://secure.phabricator.com/D6822
69 lines
2.9 KiB
Text
69 lines
2.9 KiB
Text
@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.)
|
|
|
|
= Differential Tips =
|
|
|
|
- You can leave inline comments by clicking the line numbers in the diff.
|
|
- You can leave a comment across multiple lines by dragging across the line
|
|
numbers.
|
|
- Inline comments are initially saved as drafts. They are not submitted until
|
|
you submit a comment at the bottom of the page.
|
|
- Press "?" to view keyboard shortcuts.
|
|
|
|
= Next Steps =
|
|
|
|
- Read the FAQ at @{article:Differential User Guide: FAQ}; or
|
|
- learn about handling large changesets at
|
|
@{article:Differential User Guide: Large Changes}; or
|
|
- learn about test plans at @{article:Differential User Guide: Test Plans}; or
|
|
- learn more about Herald at @{article:Herald User Guide}; or
|
|
- give us feedback at @{article:Give Feedback! Get Support!}.
|