Contributing to GHC
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.
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.
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.
ghc-prim) somewhere in my history, which I’d like to get into
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!
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
arcanist/bin to your
Link arc with your phabricator account
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
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
with this page.
Reviewer(s) we specified.
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.
comment probably doesn’t hurt and might help the next one reading the “code”.
previous patch is left, because we essentially rewrote everything. The second commit reversed everything from the first after all.
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.
displayed. We’ll mark the comment as Done…
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