Skip to content

Poor contribution experience

GHC has an exceptionally poor contribution experience. This ticket is to serve as documentation and discussion space of those issues.

Documentation

GHCs documentation is all over the place. Some information is in the user guide, some in the Haskell report, some in the GHC wiki, some in README files in the repo, some in source code comments.

Lots of things are inaccessible to contributors, even if they are in theory documented. Outdated or incorrect documentation is a frequent occurence as well.

The wiki structure is confusing and hard to search through. I end up using Google or AI to find GHC documentation.

GitLab

The self-hosted GitLab appears to be a time and money sink and yet it's one of the worst parts of contributing to GHC:

  • frequent http errors (e.g. 500 on visiting an issue or MR)
  • sometimes broken CSS/HTML, which requires clearing all browser cache
  • commenting sometimes errors out and your comment is gone
  • commenting on large MRs is often impossible, because of insane input lag in the text box (on my browser I've observed input lag of 0.7+ seconds, making it impossible to type anything)... requiring you to type the comment in an editor and copy paste it over (it's 2026... can this be real?)
  • search functionality is largely useless... searching through my email inbox is easier and more accurate
  • in general it's slow and unresponsive

CI and testsuite

CI is atrocious to deal with for a number of reasons:

  • there is at least 3 levels of CI (validate, full-ci, nightly)... in order to run full ci you have to attach a label... and that may still allow broken patches in, which then get revealed during nightly
  • obscure generation logic (generate-ci program, which looks like people just copy paste hacks around)
  • turnaround times of 6+ hours... once I kick off a build, I can basically call it a day and do something else until the next day to get feedback about my patch... paired with the next point this is insanely frustrating
  • inability to reproduce failures on obscure platforms (e.g. RiscV etc.)
  • no clear documentation on how to e.g. install new packages on FreeBSD or Windows
  • the ci-images approach makes it rather cumbersome to quickly test an environment change... now I have to create a PR against ci-images, wait for the build to finish, update the image hash in the GHC repo... get the ci-images PR merged, etc. etc. Additionally it's all written in Dhall, which has very little benefit here and is another mental overhead a contributor has to go through.

Add to this the GHC testsuite and you get a development workflow that basically consists of investigating issues for days and weeks that have nothing to do with your patch.

Wrt GHC testsuite:

  • still lots of flaky tests (I'm not sure anyone tracks when a flaky test always fails reproducibly on a specific platform)
  • the testuite code is very confusing to follow through multiple Makefiles and python shenanigns... getting to the bottom of certain failures (especially ghci tests) required me to insert printfs in random places in the python code. Lots of functions are so overloaded with functionality that you can't even document them sensibly anymore (e.g. compile_and_run).
  • non-portable: python is not very portable across systems and versions... trying to run tests may just barf out with some import or whatever errors, requiring you to figure out where the discrepancy comes from

Merging

There is no merge coordination. Literally anyone can assign to marge bot and call it a day. Large conflicts can arise and depending on who gets their changes in first, you end up having to rewrite half of your patch and start from scratch fighting CI and testsuite to get another shot at the merge queue.

Apparently, lots of broken patches make it into master too. I had to rebase some of my PRs because tests unrelated to my patch started failing.

Hadrian

Hadrian, afaiu, was supposed to be a stop-gap until cabal catches up with required functionality. But no one bothered and the hadrian build system grew out of proportion. The way it interacts with cabal is very delicate and confusing. There is parts where it invokes gcc to figure out source file dependencies... all those things are incredibly hard to debug and understand.

It's an entirely custom build system after all. You have to learn it from scratch just to contribute to GHC, which seems quite excessive.

It's also fairly unreliable. I very frequently get obscure build errors if I don't run ./hadrian/build clean... especially when I change cabal files (let's not talk about switching branches). So what's even the point of this exceptionally fine grained dependency tracking when it's not even used correctly? It's basically broken.

I think most of those things are, in fact, known. That's what concerns me the most. In my opinion the GHC project does not take good care of the contribution experience and constantly deprioritizes such issues, because the core developers have managed to work around all of these problems over time while still being productive.

It appears it's a "it works for us" approach. It's also not enough to ask outsiders/volunteers to improve this. It has to become a mentality and a constant priority to upkeep good developer experience. Otherwise you're discouraging contributions from all but the most dedicated individuals.

To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information