Differential User GuidePhorge Administrator and User Documentation (Application User Guides)
Guide to the Differential (pre-push code review) tool and workflow.
Overview
Phorge supports two code review workflows, "review" (pre-push) and "audit" (post-push). To understand the differences between the two, see User Guide: Review vs Audit.
This document summarizes the pre-push "review" workflow implemented by the tool Differential.
How Review Works
Code review in Phorge 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 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 Differential User Guide: Inline Comments.
Next Steps
Continue by:
- diving into the details of inline comments in Differential User Guide: Inline Comments; or
- reading the FAQ at Differential User Guide: FAQ; or
- learning how to use markup in comments at Remarkup Reference; or
- learning about test plans in Differential User Guide: Test Plans; or
- learning more about Herald in Herald User Guide.