Differential: Phabricator’s Code Review Application

Differential is at the heart of Phabricator's suite of tools, providing an efficient and collaborative environment for peer code reviews. This detailed sub-page covers everything you need to know about Differential, from its fundamental concepts to advanced usage.

Overview of Differential

Differential is Phabricator's tool for conducting pre-commit code reviews. It serves as a platform for developers to submit their changes (diffs) to peers for feedback before the changes are merged into the main codebase. This ensures that code is vetted for quality, consistency, and functionality by multiple team members before it becomes part of the project.

Key Features

• Inline Comments: Reviewers can comment directly on lines of code, making feedback specific and actionable.

• Revision Updates: Authors can update revisions with new changes, keeping the review process dynamic and iterative.

• Integration with Repositories: Differential works closely with Diffusion, Phabricator’s repository browser, to facilitate a seamless review process.

• Automation with Herald: Herald rules can automatically trigger actions based on Differential events, such as adding reviewers.

Creating and Managing Revisions

Submitting a Revision

To start a code review, a developer submits a 'diff' to Differential, which becomes a 'revision':

1. Prepare Changes: Write code and commit changes locally.

2. Create a Diff: Use the arc diff command to create a diff from your local changes.

3. Submit Revision: The arc diff command sends the diff to Differential, where it becomes a revision for review.

Updating Revisions

• Iterative Reviews: Developers can update an existing revision by submitting additional changes, which keeps the revision history and discussion in one place.

• Abandoning Revisions: If changes are no longer needed, a revision can be abandoned, signaling that the review should no longer be considered.

Review Process

Differential’s review process is designed to be both thorough and flexible.

Conducting Reviews

• Assign Reviewers: When creating a revision, authors can specify reviewers, or Herald can assign them based on pre-configured rules.

• Inline Comments: Reviewers provide feedback directly on the code lines that are pertinent.

• Actionable States: Revisions can be in states such as "needs review," "needs revision," "accepted," or "rejected," guiding the author on the next steps.

Automated Checks

• Linting and Unit Tests: Differential can run automated linting and unit tests to catch issues before human review.

• Continuous Integration: Integrations with CI systems can provide build status and test results directly in the review interface.

Best Practices in Code Review

Differential is most effective when used with the following best practices:

• Timely Feedback: Code reviews should be conducted promptly to avoid blocking progress.

• Constructive Communication: Comments and discussions should be constructive, focusing on improving code quality and solving problems.

• Clear Expectations: Teams should establish clear guidelines on what is expected in both the submission of revisions and the review process.

Advanced Features

For teams with more complex needs, Differential offers advanced features:

• Reviewers' Revisions: Specialized dashboards where reviewers can see all revisions awaiting their attention.

• Audits: Post-commit reviews that allow further inspection of code after it has been merged.

• Phabricator Query Language (Phriction): Custom search queries to filter and find revisions based on a wide range of criteria.

Conclusion

Differential is a powerful tool within Phabricator for maintaining high standards of code quality and facilitating a collaborative development process. By leveraging Differential's features effectively, teams can ensure that every line of code is reviewed, discussed, and improved before it makes its way into the codebase, laying the foundation for a robust and error-resistant software project.

The next pages will dive deeper into the other components of Phabricator, showcasing how Differential integrates with these tools to provide a comprehensive development workflow.