learn4haskell: a Haskell course delivered as four pull requests

The course is the pull request

The premise is unusual enough to be worth stating precisely. Learn4Haskell is a GitHub-located course that gets you into the Haskell functional programming world in four pull requests, and it is organised as a coding project, so you can complete the course without needing to exit your editor.

The mechanics are simple. When you decide to start, all you need to do is fork the project. The authors have prepared four separate modules, which are chapters, and each part contains educational material and many examples provided in a simple form that does not require you to know anything about functional programming beforehand. Each chapter also contains several exercises on everything that is explained.

The workflow is to solve the tasks, and at the end open a pull request to your fork with that chapter's solution. The maintainers then respond, and the readme is explicit about what that response is: they are happy to give feedback on your progress, explain problematic concepts, or simply support you. There is even a note that you can rely on pull requests to ask questions about a chapter even before you have solved it.

The result is a course with a built in feedback loop and a public artefact. A pull request against your own fork is a normal piece of open source work, which means the four pull requests that come out of the course are also a portfolio of the exercises you solved.

Four chapters, ordered by how hard the ideas are

The course plan is the syllabus, and it is laid out as four chapters of highlights.

Chapter one covers what Haskell is, what its particularities are, and the basics: syntax, functions, types and expressions. Chapter two is about the functional programming concepts in the language: immutability, pattern matching, recursion, polymorphism, laziness, higher-order functions, partial applications and eta-reduction. Chapter three focuses on types, covering type aliases, algebraic data types, product types and records, sum types and enumerations, newtypes and typeclasses. Chapter four is titled around the three monsters of functional programming, and those are Functor, Applicative and Monad.

The progression is deliberate and it is the standard order, which tells you the course was written by someone who teaches it. Syntax first, then the programming model, then the type system, then the abstractions that the type system exists to support. Somebody who arrives knowing Haskell will recognise the shape immediately.

The readme recommends going through the chapters in order, but adds that if some of them feel familiar you can skip to the next one, and that each chapter contains unique information and covers different topics. The estimate given is an evening per chapter, with the caveat that the chapters are stuffed with information but are meant to be completed without additional resources.

The stated endpoint is that you should be able to independently create and read basic Haskell code and understand Monads and other famous concepts of functional programming. That is a real, if modest, goal, and the course is explicit that it is aimed at beginners rather than at experienced developers looking for advanced material.

The test suite is the teaching mechanism

The Makefile shows how the course is built, and it is the most interesting file in the repository.

Each chapter has two test targets. Each target runs the doctests for that chapter and then the chapter's test executable filtered to a particular group of tests:

cabal test doctest-chapter1 --enable-tests --test-show-details=direct
cabal run learn4haskell-test --enable-tests -- -m "Chapter1"

The basic variant of the same target filters on a different group, with the name Chapter1Normal for chapter one and the matching name for each of the others. So the two groups are the plain chapter group and the Normal variant, and the filter argument selects between them.

That is a neat design for a teaching repository, because it means the student is not just reading the material but running the same checks the maintainers run. The doctests are the examples in the prose, and they are executable, which means an example in the chapter cannot quietly rot. The chapter test executable is the exercises, and the solution you put in the pull request has to pass it.

There is a target that runs everything at once:

cabal test all --enable-tests --test-show-details=direct

and a clean target that runs the cabal clean command. The build target uses the cabal build command with tests enabled and with GHC environment files always written, which is the setting that makes an editor or an IDE able to find the package's modules without a separate step.

Cabal, a package file and the toolchain you need

The project is a normal Haskell package with a few extras.

There is a cabal file at the root, a source directory holding the chapter modules, a test directory, a Makefile with the targets above, a changelog, a code of conduct, a licence file and a readme. The chapter sources are named by number, with the first chapter living in a file called Chapter1.hs, and the readme tells you to open that file and start learning and solving tasks.

The toolchain is Cabal and GHC, and the getting-started list is short: fork the repository, add the hacktoberfest topic to your fork, enable GitHub Actions for the forked repository, install the Haskell compiler, open the first chapter file, and then open a pull request to your fork with the solution.

Two details in that list matter more than they look. The first is the topic, and the readme explains that without it the pull requests will not count, with a link to the Hacktoberfest rules. The second is GitHub Actions, which is step three of the list, which means the test suite runs on your fork against your solutions. For a course whose whole loop is a pull request, having continuous integration run the doctests and the exercise tests is what makes the feedback automatic rather than dependent on a human noticing.

There are two developer quality tools configured. A stylish-haskell configuration file at the root, which is the formatter the project uses for its own style, and a Gitpod configuration, which gives you a browser based development environment if you would rather not install a compiler locally.

The licence is MPL-2.0, which is the file level copyleft licence, so a fork that you modify and redistribute carries the obligation on those files while the rest stays open.

Hacktoberfest was the door, the course is the room

The origin story explains the design.

The project began around Hacktoberfest, the annual event where people contribute to open source projects, with the reasoning that most contributors stay inside the communities they already know, and the question the authors asked was why not use that time to learn something challenging that you never had time for. The pitch is that you can get the benefits of Hacktoberfest while learning functional programming with Haskell, and the readme lists three benefits in parallel: four pull requests to get the t-shirt or plant a tree under the Hacktoberfest rules, four pull requests to learn to program in Haskell, and four pull requests to blow your mind.

The framing is dated, and the readme acknowledges it in a prominent notice at the top, saying the course continues as usual after Hacktoberfest. The results of the 2020 edition are written up in a blog post on the same site.

That notice matters for a reader evaluating the repository today, because it tells you the course is not a hacktoberfest gimmick that has stopped working. The two timelines continue in parallel, and the goals list is the honest version of what the project is for: help others learn Haskell, give a beginner-friendly and self-consistent course with theory and practice in the same place, explain topics before each task while staying concise, help people who want to participate in open source but also want to learn, provide review and feedback so people are never alone, and give people who complete it a strong basis to continue their functional programming studies.

The last point is the one to weigh. This is a course that aims to get you to the point where you can read and write basic Haskell, and the honest expectation it sets is that you will need to keep studying afterwards.

Editorial conclusion

learn4haskell is a good fit for a complete beginner who wants a structured path into Haskell with feedback and a visible record of progress, and for a contributor who wants the practice of opening four pull requests to their own fork. It is a poor fit for someone who already writes Haskell, who is told in the readme that the advanced material is not the point here, and it is a poor fit for a self-paced learner who wants to work offline, since the review and feedback loop depends on the pull request. Before you start, install a Haskell compiler, enable GitHub Actions on your fork so the test suite runs on your solutions, and read the chapter order in the readme so you know which exercises feed the doctests.

Frequently asked questions

Official sources

1. Issues
2. kowainik/learn4haskell on GitHub
3. License: MPL-2.0
4. Project website
5. README