recaptime.dev
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Differential User Guide
2@group userguide
3
4Guide to the Differential (pre-push code review) tool and workflow.
5
6= Overview =
7
8Phorge 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
12This document summarizes the pre-push "review" workflow implemented by the tool
13//Differential//.
14
15= How Review Works =
16
17Code review in Phorge is a lightweight, asynchronous web-based process. If
18you 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
31The 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
40The preferred way to create revisions in Differential is with `arc`
41(see @{article:Arcanist User Guide}). You can also create revisions from the
42web interface, by navigating to Differential, pressing the "Create Revision"
43button, and pasting a diff in.
44
45= Herald Rules =
46
47If 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
49just some intern who you don't trust) you can write a Herald rule to
50automatically CC you on any revisions which match rules (like content, author,
51files affected, etc.)
52
53Inline Comments
54===============
55
56You can leave inline comments by clicking the line number next to a line. For
57an in-depth look at inline comments, see
58@{article:Differential User Guide: Inline Comments}.
59
60
61Next Steps
62==========
63
64Continue by:
65
66 - diving into the details of inline comments in
67 @{article:Differential User Guide: Inline Comments}; or
68 - reading the FAQ at @{article:Differential User Guide: FAQ}; or
69 - learning how to use markup in comments at @{article:Remarkup Reference}; or
70 - learning about test plans in
71 @{article:Differential User Guide: Test Plans}; or
72 - learning more about Herald in @{article:Herald User Guide}.