How to Review a Pull Request on a Haskell Project
A contributor sent a 38 line patch to a logging package I help maintain. It added one instance, had a reasonable commit message, and sat untouched for five months. The reason was not laziness.

A contributor sent a 38 line patch to a logging package I help maintain. It added one instance, had a reasonable commit message, and sat untouched for five months. The reason was not laziness. Every time I opened it I realised I could not tell in under a minute whether that instance changed the public interface, so I closed the tab and did something else. The contributor eventually deleted the fork.
That failure was mine, and it came from not having an order to work in. Reviewing a Haskell pull request is mostly mechanical, and the mechanical part answers the expensive questions first: does this change what downstream code can compile against, and does the build still pass with the bounds the package actually declares. Once those two are settled, the human part of the review takes twenty minutes instead of an afternoon.
Three questions before you read the diff
Open the file list, not the code. You are looking for three things, and the answers change how much of your attention the rest deserves.
First, did any module export list change? A new export, a removed export, a widened type, a new instance for a type you own: all of these are interface changes, and under the Package Versioning Policy they drive the version bump rather than the other way round. I have reviewed patches where the diff looked like an internal refactor and the export list told a different story.
Second, did the cabal file change? A new dependency is the single most expensive line a contributor can add, because every downstream user inherits it and every bound you accept becomes a bound you maintain. A loosened upper bound deserves the same suspicion as a new dependency.
Third, is there a test that fails without the patch? Not a test that passes with it. If you cannot see the test fail on the base commit, you are reviewing a claim rather than a fix.
Pulling the branch and building it yourself
Reading a diff in a browser tells you what someone wrote. Building it tells you what the compiler thinks, and on a typed language that gap is where most review time is wasted. Fetching a pull request as a local branch takes one command, with 412 standing in for the number: git fetch origin pull/412/head:pr-412, then check it out and build.
What I run, in this order, on a package with a normal test suite:
- Build the library alone first. If the library fails to compile, nothing else matters and you have saved yourself the test suite link time, which on a package with a few hundred modules runs four to six minutes on a laptop.
- Build with warnings turned into errors. Most contributors develop with the project defaults. If your CI is stricter, you want to see that failure now rather than after you approve. The flag is the Werror one, set in the cabal file under ghc options.
- Run the test suite twice. Once normally, once with a different random seed if the suite uses QuickCheck. Property tests that pass on one seed and fail on another are the most common surprise in Haskell review, and the failure is usually in the patch, not the generator.
- Build the documentation. Running haddock catches malformed comment markup and dead references to renamed functions. It takes under a minute and it is the check nobody runs until the Hackage upload fails.
- Check the bounds resolve downward. If the patch touches dependencies, build once against the oldest versions your cabal file allows. A bound of 2.0 and up that nobody has compiled since 2.0 is a bound that is already broken.
On a laptop with an eight core processor and a warm store, that whole sequence is about nine minutes for a mid sized package, and I start it before I read a line of the implementation. The build runs while I read.
What the types already prove, and what they do not
The useful part of reviewing Haskell is knowing which objections the compiler has already handled for you. If a function takes a non empty list and the patch passes it a non empty list, there is no point writing a comment about the empty case. If a record field is a newtype over Text, you do not need to ask whether a user id got swapped with an account id. Those reviews belong to languages where the types do not say so.
Three categories of defect the type checker will cheerfully let through, and these are where review earns its time:
Space leaks. A lazy accumulator in a fold, a thunk retained in a long lived map, a strict field that the patch turned lazy. The type is identical either way. I look for every new fold and every new record field, and I check whether a bang pattern or a strict field annotation disappeared in the diff.
Exception behaviour in the wrong place. Code that acquires a handle or a connection and does not use a bracket style wrapper will type check perfectly and leak file descriptors under an asynchronous exception. Any patch touching resource acquisition gets read twice.
Instances that violate their laws. A Monoid instance that is not associative, an Ord instance inconsistent with Eq, a Functor that changes shape. The compiler accepts all of them. This is also the one case where I will ask a contributor to add property tests before approval rather than after, because the laws are exactly what properties express well. If the project has no QuickCheck setup, that is a separate issue, and the groundwork belongs in your CI configuration rather than in this pull request.
Why I stopped asking for style changes
The standard advice is that review should enforce a consistent codebase, so you ask for the import block to be sorted, the where clause to be indented your way, the type signature to be split across lines. I did that for about two years and the result was that contributors made the edits, learned nothing, and never came back. Roughly a third of first time contributors to the packages I watch submit exactly one patch, and a style heavy review is a decent way to guarantee it.
What replaced it was a formatter in CI and a one line note in the contributing file saying which one. Fourmolu or Ormolu, pinned to a version, run as a check rather than a suggestion. The machine makes the style demand, nobody argues with the machine, and the human review spends its budget on whether the instance is lawful. The same reasoning applies to naming: I will argue about an exported name, because exports are permanent, and I will leave a local binding called xs alone.
The other piece of common advice I have given up on is reviewing everything within 48 hours. Unpaid maintenance does not work on a service level agreement. What does work is saying in the pull request template that review happens in batches, roughly every other week, and then actually doing it. Contributors are fine with slow if slow is predictable. They leave when a patch sits in silence, which is what happened to that logging instance.
Closing a pull request without losing the person
Some patches should not land. The honest close names the reason, separates it from the quality of the work, and says what would land: this adds a dependency we cannot carry, here is the same behaviour as a function users can define themselves in four lines, and I would merge that as a documentation example today. The reasoning behind that kind of refusal is worth writing down once in the repository, and the trade offs are covered in how maintainers decide what to reject.
When a patch does land, the review is not finished until the changelog entry exists and the version bump matches what the export list did. A merged interface change with a patch level bump is a broken build for every user who trusts the bounds, and the rules for that are set out in the versioning policy for maintainers. I add the changelog line in the merge commit myself about half the time, because asking for it adds a round trip for one sentence.
FAQ
Should I review a patch I do not fully understand?
Review the part you do understand and say which part you did not. A comment saying the API change and the tests look right, but someone who knows the STM code should check the retry logic, is more useful than silence and far more useful than an approval you are not sure about.
How do I handle a patch with 30 commits?
Review the combined diff, not the commit series, unless the contributor clearly built it as a readable sequence. Then squash on merge and write the message yourself. The history that matters to users is the changelog, not the order someone fixed their own typos.
What if CI is red for reasons unrelated to the patch?
Fix the unrelated failure on the main branch first, in its own commit, then rerun. Merging through a red build teaches everyone that the build light means nothing, and after that nobody looks at it.
Can I push my own fixes to their branch?
You can when the fork allows maintainer edits, and it is the right call for a typo or a bounds tweak on a patch that is otherwise ready. For anything touching logic, say what you plan to push before you push it. Finding your own name on code you did not write is a strange experience for a first time contributor, and the first contribution is the one that decides whether there is a second.
More in Open Source
Open Source
How to Deprecate a Haskell Package Without Breaking Users
I retired a small Haskell package in 2023 and did it in exactly the wrong order.
Open Source
How to Vet a Haskell Dependency Before You Add It
A student in my second year class added a JSON library to her project because it was the first result she found and the README...
Open Source
How to Write a Haskell Bug Report Maintainers Can Fix
You hit a crash in a Haskell library, open the issue tracker, and type three lines about what broke.