Written by Moritz
on 

Contributing to GHC

via Phabricator

About two weeks ago I gave a talk on “Contriubting to GHC via Phabricator” at the local haskell.sg Meetup. Sadly the microphone died after a few minutes into the recording, and as such the video has no audio for most of the talk and is pretty useless. As the topic might be of interest to those who could not attend, I’ll write down the content of the talk as good as I can.

Phabricator?!

Let’s start with what Phabricator is, Phabricator is the code review tool GHC uses. It was originally developed at Facebook by Evan Priestley, who has since founded Phacility, Inc where the development of Phabricator continues.

Phabricator is not just used at GHC, it is also used for other projects like LLVM, the Wikimedia Foundation, FreeBSD, and a many more.

I will now try to demonstrate the usage of Phabricator for a simple change (with many pictures!).

Creating an account

phabricator.haskell.org, this is the first screen you will be greeted with. We will proceed to open an account so we can do something useful.

form. While you can register a new account, I would suggest to use on of the available alternative account connectors.

Figure 3: For this example, we’ll use GitHub.

Figure 3: For this example, we’ll use GitHub.

will still be required to provide an email address.

code, or even submit our own code for review. So let’s do this next.

I have a change in my tree

Phabricator is not really concerned how your local tree looks like. It essentially only cares about differences. So you can go wild with your local branch management; use git however you like.

For Phabricator try to think in patches (differences) instead of commits.

For the following example, I’ve been working on cross compiler related issues and while doing so, I usually accumulate lots of different fixes in my branch.

to ghc-prim) somewhere in my history, which I’d like to get into GHC proper.

and cherry-pick the relevant commit onto it. You could do this however you like. Just make sure you have a handle on the range for your patch.

git diff origin/master should tell us. // Note the stupid white space!

Enter arcanist

Phabricator has a companion tool called =arc=anist:

“arc — arcanist, a code review and revision management utility”

To install it, we need to clone the following two repositories:

$ git clone https://github.com/phacility/libphutil.git
$ git clone https://github.com/phacility/arcanist.git

Then add arcanist/bin to your PATH.

Next we’ll need to tell connect arc with our phabricator account on phabricator.haskell.org. To do this we need to run the follwing command from within the ghc repository

ghc $ arc install-certificate

get it from.

following page. Simply copying the API Token …

to properly link your haskell phabricator account with your ghc repository. This needs to be done only once!

the offset, but usually arc should figure out the origin/master offset on its own.

wants to be helpful here and tell us that we have lots of untracked files in our repository. If you are sure you have committed everything you want to submit for review, it’s safe to say =y= here.

asked to fill out some metadata about your patch.

summary and added Ben Gamari as a reviewer. Let’s hope he’s not too busy!

the patch. And of course it found the stupid white space from before. It is however helpful enough to ask us if we just want to have this change (removal of white space) applied.

arc apply the patch. Next it wants to know if we want to amend HEAD. And yes it makes sense to just amend this into the last commit. So I’ll go with =y= here.

phabricator; and we got a Differential identifier back D4253 in this case.

with this page.

Reviewer(s) we specified.

Figure 21: And even further down we can see the patch we submitted.

Figure 21: And even further down we can see the patch we submitted.

Let’s do a self-review here.

displayed but not the gray dashed border. It is not submitted. I think phabricator UI could be a bit better.

that our remarks are actually submitted and others can see them.

the timeline.

comment probably doesn’t hurt and might help the next one reading the “code”.

new patch.

previous patch is left, because we essentially rewrote everything. The second commit reversed everything from the first after all.

Figure 29: Time for arc diff origin/master again.

Figure 29: Time for arc diff origin/master again.

Figure 30: And again we are greeted with the untracked files screen.

Figure 30: And again we are greeted with the untracked files screen.

because we are updating a differential and are not creating a new one. Here we can specify what we changed. By default it will pull information from the commit messages.

Differential.

Figure 33: Looking at the timeline we see the new update item as well.

Figure 33: Looking at the timeline we see the new update item as well.

displayed. We’ll mark the comment as Done…

actually submitted.

the timeline.

Where to go from here?

Now someone will have to come and review the code, and select the “Accept” Action. If the code is accepted, you can run arc land *if you have commit access to GHC*/. If you do not have commit access worry not, someone with commit access will usually aggregate accepted diffs run /=./validate= on them and if that passes push them to the GHC repository.