Phabricator/Differential

Differential is the code review tool in Phabricator. As per discussions with the technical community the WMF Release Engineering Team is driving the migration to Differential from Gerrit. See the #Gerrit-Migration Phabricator project.

Getting Started

Install Arcanist

To submit patches/changes ("Differentials"), install Arcanist, the command line tool that interfaces with Differential.

Background reading

1. Read these recommended user guides from the upstream documentation on the two main parts of Differential code review:
   1. Differential User Guide
   2. Arcanist User Guide
2. Read these recommended guides from upstream documentation on how code review happens and why:
   1. Writing Reviewable Code
   2. Differential Test Plans
   3. Bonus points: Read this blog post from the lead developer of Phabricator about how and why Differential does code-review.

Done

Now, go contribute code!

How can I do this thing I did in Gerrit?

Firstly, not all actions that Gerrit provides will be available in Differential. This is by design. Not all code-review tools act exactly the same and design decisions are made to make the code-review tool internally consistent. Thus, please first try to understand how Differential and Arcanist are meant to be used (by reading the above links and trying things out) before asking for feature parity with Gerrit.

For code contributors / authors

Take over another author's change

There is the "Commandeer Revision" action on every open diff. This will, as the name suggests, allow you to take over a change. Do this when, for example, the original author is unresponsive but you want to move the change forward.

Amend another author's change

Instead of in Gerrit:

  git-review -d 12345 # this applies change 12345 to your checkout of the repo
  # make minor change to fix typo or rebase and fix minor conflict
  git commit --amend -a
  git-review -R
  # Optionally CR+2/merge that patch

In Differential you do (still 3 commands, minus whatever fixes you make):

  arc patch D12345 # this applies D12345's change to your checkout of the repo
  # make minor change to fix typo or rebase and fix minor conflict
  git commit --amend -a
  arc diff --update D12345 HEAD^
  # Optionally 'arc land' if you simply want to commit the change

For code reviewers

Get notifications about patches submitted to your project

If you are a maintainer, please consider configuring the Owners tool to send you an email for new patchsets in a project (repository). Owners allows you to create "packages". A package consists of one or more directories in one or more code repositories. When someone proposes changes which affect code in a package that you own, you can automatically get notified via the "Auto Review" setting. Additionally, packages can trigger audits which alert you to any commits which haven't been reviewed by one of the package owners. To learn more about the owners tool, read the upstream documentation. After that, please use this form to create packages covering the code you care about.

Avoiding arcanist

Since the migration to Differential has been scrapped in favor of continuing with Gerrit, we have been slowly removing Phabricator-hosted repositories. Some repositories, mostly those related to Phabricator or its extensions, are still managed with Differential, and you might find yourself in the rare situation where you need to submit a patch/commit to a Phabricator managed repository. If you do not want to go through the trouble of installing and configuring arcanist, then there is an alternative way to submit a change using the web interface. To do this you need three things:

1. the name of the repository for which you want to submit a change,
2. a local copy of the repository. You can just use a mirror, like those available in Gerrit, and
3. the uncommitted changes locally.

   Optionally, you can put these in a diff file by running git diff > change.patch.

To submit a change, visit phab:/differential/diff/create/, which can also be found by navigating to Differential and then clicking on "Create Diff". There you can either paste your diff created by git diff or upload a diff file created by git diff > change.patch.

After clicking "Create Diff", you'll be shown a screen where you can input a summary, add tags, subscribers and reviewers, similar to creating a task.

Finally, after publishing the diff, don't forget to request a review by scrolling down the screen to the comment text box. There is a dropdown with the action "Request Review", which is a required action to get reviewers notified.