Phabricator


 * See ongoing discussion, and a new test instance linked, in Architecture meetings/RFC review 2014-02-05.

Facebook engineers rave about Phabricator, describing it with glowing terms like "okay" and "mandatory".

Phabricator is a software development tool written by Phacility (all former Facebook engineers), and currently open sourced. It is intended to make it easier to write, review and share source code.

This page is a documentation for evaluating this tool within MediaWiki.

Issues that need to be resolved before it is usable for us are listed at Phabricator/todo.

Checkout
The git repo currently live in my github account, based off of the test git repo prepared by chad with a few changes. Check that out to your favorite folder.

git clone https://github.com/johnduhart/mwphb.git

Note: this tutorial will not cover how to use git in-depth.

Congrats! You now have a full (albeit stale) MediaWiki install! Pat yourself on the back.

Create an account
Waddle on over to the web interface and register.

At the moment Phabricator only supports OAuth login (via GitHub or Google). I plan to add LDAP support at a later time.

Setup
Phabricator requires a program in the client PC in order to operate (You can skip this and use raw diffs hardcore but I won't go over that right now). The source code for the program is here. I've scripted most of the install so you can spend more time fixing bugs.

Run this and answer the questions.

./arc-setup

After that is done, you just need to source your profile and you should be able to run arc

arc help

If something goes wrong, please send me the output on IRC.

Make a change!
This whole setup would be pointless if you couldn't do anything. Lets' start by creating a new branch to work in.

git checkout master # Just make sure we're in master git checkout -b feature # Create a feature branch, name it something creative though

Now, make a change! For example:


 * Take a recent commit from svn and apply it here
 * Add crap to some file so we can reject your changes
 * etc.

When that's done, add those files to your index, or just use  on commit. Now, commit your changes

git commit

You may notice that we've hijacked your commit message!

<>

Summary:

Test Plan:

Reviewers:

CC:



This message is intended to be parsed by Phabricator when you submit your diff.

Note that all of these fields can be configured to our liking
 * Title Title for your change
 * Summary Longer and more descriptive summary of what has been changed
 * Test Plan A repeatable list of steps which document what you have done to verify the behavior of a change. More info
 * Reviewers People who should review this change (Optional)
 * CC People to notify about this change (Optional)

Fill out the fields and commit your change. To submit your change to differential, run this command

arc diff master

This command takes the difference of your branch against the master branch and submits it for review. Before doing so, it runs a linter over your changed code and (one day) unit tests.

Review a change
Now we need to actually review a change. You could browse the list of revisions or wait for someone to assign one to you.



Here, we have a revision waiting on us to review. On this page you can see information about the revision, as well as the change itself. How nice. Now, let's review this revision.



Phabricator allows you to make inline comments to changes, as shown here. Be sure to submit them using the comment form at the bottom of the page.

But let's say you wanted to check out this revision for yourself. On your mwphb repo, run this:

arc patch D5

This will checkout a new branch and apply the patch there for your testing pleasure. Since Roan truly is the API king, we can accept this revision. From the revision view, accept the revision by selecting "Accept Revision" from the action dropdown.

Committing the change
Unlike gerrit, Phabricator does not automatically commit the revision. The reviewer (or the author, if they have access) must commit the revision. This is a fairly straightforward process. Checkout the commit using  (if you haven't already), and run the land command

arc land D5

That's it, the tool will merge the change into master and push it.