UPDATED 2019-08-22: See the end of the post for how this turned out.
This post serves as notes and explorations of my first patch to GHC. I’m going to start from the very beginning – so it might be kind of boring!
First thing’s first: check out the documentation. It was a little overwhelming at first, until I noticed the Newcomer’s info link. This one is much easier to get started with – has all the directions you need to get GHC building! I ran the commands, GHC downloaded and built, and soon all was ready to go.
The next thing to do is to pick a ticket to implement. The Newcomer’s Info page has a list of newcomer friendly tickets. This ticket seemed relatively easy – a small change to the parsing rules to allow trailing and leading commas to data constructor export lists. I made a comment indicating that I would try to make a patch for it.
This was fun – GHC has a huge codebase.
Fortunately, the parser was relatively easy to locate.
There’s a directory compiler that has the compiler, and parser is located right under there.
As an aside:
I use FZF to fuzzy locate files in projects via fzf.vim.
This lets me open vim up, type some barely coherent garbage in, and mostly find what I am looking for.
I do this as my primary means of exploring a code base – I’ll whack <leader>e which lets me fuzzy search file names.
The Haskell language parser uses Happy, the parser generator for Haskell. I used Happy briefly when working on the Appel compiler book, but have otherwise never used a parser generator.
How do testing!?
I used my FZF trick from above and did a fuzzy search for testparse.
This showed me that there was a testsuite directory that included a tests/parser directory.
There’s a testuite/README.md file that has more information on how tests run, and also a link to the official test suite documentation.
That page included a link on how to add a test.
I ran the test suite at first, and – holy crap – it takes a LONG time to run the entire GHC test suite!
So I killed it, reread the README, found that you can run just a section of a test, and then did that.
I followed the directions to add a test and came up with this commit. The test failed, so I’m good to go.
Now, it’s time to get that test passing.
I’m not super familiar with parser combinators, so I tried stuff until the test passed.
The test suite readme had instructions on running a single test with make TEST=T12389 which I gladly took advantage of.
To make compiling things faster, you can cd into the relevant directory and run make.
For the parser, that’s compiler.
That work ended up with this commit. I made the test example a little bigger to test for more stuff.
This is where things get Weird, if you’re like me and you started getting into open source after GitHub had essentially established world dominance. GHC is the first project I’ve ever worked on that was hosted on a non-GitHub (or GH-like site, like BitBucket or GitLab).
But, before I get too excited, I look at the instructions for how to submit a patch to GHC. After making the commits, it asks to “validate the commits” using Travis or a validation script.
Looks like I can just run ./validate in the GHC repo.
Except that gets me a sphinx-build not found error.
Fortunately, that’s easy to fix by installing it via apt-get.
./validate then proceeds to run for a VERY long time.
… Still running…
Ok, at this point I got impatient.
The directions for submitting a patch using Phabricator are pretty great. I ran the relevant commands, and now my patch is on the website. Neat!
At this point, it’s time to wait for code review, implement any requested changes, and then pat myself on the back for contributing to GHC. You can do it, too!
It’s been almost two years since this whole process got started. The contribution did not land. Here’s what happened.
hvr left a comment indicating that this had been thought through, and it would need a much larger investment of time and energy.
I was told to make a GHC proposal so that it could go through the official process.
So, I made an official GHC proposal.
The proposal discussion ballooned to 166 comments at the time of writing this update.
Here’s my summary:
TupleSections, though. How should we handle it?Matt: OK, so there are two options for this:
ExtraCommas and TupleSections completely incompatible.ExtraCommas.Let’s pick one and get on with this. I want this off my plate so if you haven’t decided in a week then I’m closing it out.
And so I will not be contributing to GHC until they’ve significantly improved their processes for newcomers.