Differential: Phabricator’s Code Review Application

Differential is an extensible code review application originally developed as part of the Phabricator suite. Designed to integrate seamlessly with a developer’s existing workflows, Differential aims to optimize the process of proposing, reviewing, and landing changes within a codebase. It offers a centralized platform for conducting both pre-commit reviews, making it a key part of maintaining code quality, consistency, and long-term maintainability in software projects of all sizes.

Core Concepts

1. Revisions: At the heart of Differential is the concept of a revision, which represents a single proposed change or a set of related changes. A revision includes:

   • Diffs: The actual code changes, highlighted and contextualized.
   • Summary & test plan: A textual description of what the change does and how it has been tested.
   • Reviewers & subscribers: A list of engineers and stakeholders responsible for reviewing or interested in the code.

   By structuring proposed changes in this formal manner, Differential ensures that reviewers receive the necessary context to evaluate code effectively.

2. Inline and contextual comments: Differential’s review UI allows reviewers to leave inline comments directly on specific lines of code, reducing ambiguity and promoting detailed, line-by-line discussions. This makes it easier for authors and reviewers to track feedback, request clarifications, and identify exactly what needs refinement. Discussions can be easily revisited and serve as an audit trail of the decision-making process.

3. Workflow integration and automation: Differential integrates smoothly with other Phabricator tools (such as Herald for automated rules and Harbormaster for continuous integration), as well as external services. For example, you can configure:

   • Automatic linting and unit tests: Trigger external builds or tests when a revision is updated.
   • Herald rules: Automatically add reviewers, block changes that don’t meet certain criteria, or require specific approvals based on project-specific policies.

   These integrations help ensure that code must pass certain quality gates before it can be landed, thereby reducing defects and regressions.

4. Review states and actionable statuses: Each revision in Differential progresses through well-defined states, such as “Needs Review,” “Accepted,” and “Needs Revision.” Authors and reviewers can take standard actions—like “Request Changes” or “Accept”—to signal whether the code meets the required standards or must be improved. This clear workflow ensures everyone understands where a proposed change stands at any given time.

Collaboration and configuration

• Flexible permissions and policies: Differential respects Phabricator’s robust policy system, allowing administrators to fine-tune who can create revisions, who can act as a reviewer, and who can land changes. This ensures that code review processes scale across large organizations and multiple teams while maintaining appropriate governance.

• Custom fields and metadata: Teams can configure custom fields in Differential to capture additional metadata—such as related tasks, priority, severity, or component area. Such fields can be used by automation, reporting, or to enforce unique internal engineering guidelines.

Example workflow in Differential

Consider a scenario where a developer, Alice, wants to add a new feature to an internal microservice:

1. Authoring a revision: Alice creates a new feature branch in Git, implements her changes, and uses the arc diff command (part of Phabricator’s command-line tool Arcanist) to upload her work to Differential. The code is encapsulated as a revision, complete with a summary and test plan.

2. Assigning reviewers and policies: Phabricator’s Herald rules automatically assign the backend team as reviewers based on the service directory the changes affect. Additional subscribers (such as a lead architect) are also added, as per organizational rules.

3. Performing the review: Bob, a backend engineer, opens the revision in Differential. He leaves inline comments suggesting improvements to the error-handling logic. Carol, a QA engineer, runs the automated tests and verifies that the changes pass all checks before leaving a comment noting that tests passed successfully.

4. Accepting and landing changes: After Alice addresses Bob’s feedback and updates the revision, Bob “Accepts” the change. Alice then uses arc land to merge the revision, at which point Differential updates the revision’s status to indicate that it has been closed and successfully integrated.

Comparing Differential with other code review platforms

Graphite, another code review platform, shares some conceptual similarities with Differential but also takes a somewhat different approach. While Differential is deeply integrated into the Phabricator ecosystem, focusing on rich administrative customization and a flexible, policy-driven workflow, Graphite is often praised for its lightweight, developer-centric approach. Graphite emphasizes an improved developer experience, especially around creating and reviewing stacked commits and streamlining the creation of cohesive, reviewable branches.

Summary

Differential is a feature-rich, policy-driven, and highly integrable code review system that forms a cornerstone of Phabricator’s development workflow suite. Its flexibility, fine-grained permission controls, and deep configurability make it a great choice for large organizations or complex engineering environments.