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. This is fine if you are creating feature branches from off of that branch. However if you use the same branching model as myself, where I create a develop branch off of the master branch and then further branch from this features branches, then you’ll want to tell Phabricator to use the branch:

  $ origin/develop

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
  • squish: git status && git commit -a --amend -c HEAD

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 develop
  $ git checkout -b newfeature
  $ vim somefile.js
  $ wip
  $ arc diff

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

  $ git checkout develop
  $ git checkout -b newfeature2
  $ ... # Continue as above

To update a change:

  $ vim somefile.js
  $ squish
  $ arc diff

To pull in updates from other contributors:

  $ git checkout develop
  $ git pull
  $ git checkout newfeature
  $ git rebase develop

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.