About 4 min read

Phabricator is our internal code review and project management tool. It is made up of a number of applications that perform certain tasks, the big ones are:

  • Differential - This is the main code review application, when you want to make a change you create a ‘diff’ in Differential using Arcanist, this is then reviewed and approved before it can go into the repository
  • Maniphest - This is a task tracking tool linked to Differential
  • Diffusion - This allows you to view all of our code in our repositories
  • Phriction - This is a wiki

Other applications include:

  • Audit - this is used for auditing post commit (we do pre-commit) so we don’t really use this
  • Herald - you can setup a herald rule to automatically notify you when somebody checks in code into a project that you own
  • Phame - this allows you to setup a blog on your own website managed by Phabricator
  • Pholio - this is a PixelCloud / Dribbble clone for showing off UI mocks
  • Conpherence - this is a team chat tool (very alpha!)
  • Ponder - this is a Q+A tool
  • Calendar - this is an out of office calendar
  • Image Macros - this allows you to insert images / memes in comments
  • Paste, Slowvote, Countdown and Fact

You may also hear the following terms

  • Diff - this is a set of changes made up of revisions that needs to be approved
  • Revision - a diff is made up of many changes, if I update a diff, I add a revision
  • Tasks - these are todo’s in Maniphest
  • Arcanist - the command line tool for Phabricator
  • Repository - all of our source code stored as a series of commits
  • Commits - An approved diff that is committed into the repository

Upon your first diff in Phabricator, it will ask you from which branch it should base its differentials. By default this will be the origin/master branch.

Quick Workflow Reference

This is how I use arc with Git.

I use an amend/rebase mutable-history workflow where each idea is always represented by one commit. I never make checkpoint commits, and I only need to write git commit messages once per feature (and perhaps amend them), and I never merge. I have three git aliases:

  • wip (“work in progress”): git commit -a -m "chore: work in progress"
  • amend: git commit --amend --no-edit
  • force: git push --force

Here’s a very quick summary of the code review workflow. Phabricator will automatically unit test and lint (check the code for formatting errors) the code. To work on a new feature:

git checkout master
git checkout -b newfeature
vim somefile.js
git wip
arc diff

To work on another feature afterwards, or while you wait for review:

git checkout master
git checkout -b newfeature2
... # Continue as above

To update a change:

vim somefile.js
git amend
arc diff

To pull in updates from other contributors:

git checkout master
git pull
git checkout newfeature
git rebase master

To commit a change to the develop branch:

arc land

Other commits

If you don’t have commit permissions then an administrator can commit a diff into the repository for you (you need to create a diff).

[!NOTE] This requires admin permissions.

arc patch --nobranch Dnnnn
git commit --amend -C HEAD --author '<[email protected]>'
git push

General Guidelines

  • Break large projects into small steps that take no longer than a day or two to complete. Most steps should be even smaller, and take no longer than a few hours. In the beginning, I’ll help you do this, but over the course of the program you should begin doing it yourself. See Writing Reviewable Code.
  • Even if you’re working on a huge project, you should never have thousands of lines of code or multiple days of work in a local/feature branch. While there are varying approaches to remote feature branching in industry (where new features are developed slowly in a giant remote branch), this project avoids it in all cases (see Recommendations on Branching). Break things into small iterations.
  • If you aren’t already familiar with Git, you can find some workflow recommendations at Arcanist Workflows.
  • A general overview of source layout is available at Phabricator Code Layout.
  • Project coding conventions are here: General Coding Standards, PHP Coding Standards.
  • You can find a history of the project at Phabricator Project History.