RFC: Begin Cabal development commentary

[phadej]

IMHO it can be a part of user's manual. Some topics to begin with are implementation commentary of

• solver
• backpack
• new-build
• parsec parser

[23Skidoo]

See also https://github.com/haskell/cabal/wiki/Source-Guide.

[phadej]

@23Skidoo didn't know about that!

[ezyang]

This shouldn't stop you from working on it, but I have been working on a solver document. It is not very far along though.

[23Skidoo]

@ezyang BTW, what's the fate of that solver document? Maybe you can put your draft on the wiki if you're no longer working on it.

[ezyang]

Apparently, I only wrote the intro :)

.. highlight:: console

Whither dependency solving
==========================

Code bases with no external dependencies are easy to build: you just,
well, build everything.

But the usual project is not an island unto itself: rather, it is
composed from other packages written by a heterogenous set of authors.
Each of these packages has multiple versions which may or may not be
compatible with one another, giving rise to the nontrivial problem of
determining a set of packages which are mutually compatible with each
other.

How can you solve this problem?

- You could rely on some third party (Stackage) to tell you
  what your version assignment should be.

- You could pick some version assignment (e.g., the latest versions
  of everything), and then tweak it until you find an assignment that
  works.

- You could use a *dependency solver*, which automates the process of
  testing version assignments to find a satisfying assignment.

Generally speaking, you would rather use the first two approaches if at
all possible.  But sometimes there is no pre-existing version assignment
that is known to work, and the obvious "by-hand" assignments don't seem
to work.  In such cases, the dependency solver can be an extremely useful
tool for generating satisfying assignments.

What a dependency solver does
=============================

The dependency solver is a pure function of type ``DependencyResolver``.
The solver takes as input:

1. The platform we are building

[hvr]

@ezyang btw, your introduction makes it sound as if dependency solving was a kind of discouraged last-resort you should avoid whever you can... whereas dependency solving lies at the core of the Hackage/Cabal/PVP ecosystem... ;-))

[phadej]

https://github.com/haskell/cabal/wiki/Source-Guide is becoming more and more outdated. Maybe it's better to admit we don't have resources to maintain it?

[23Skidoo]

We can add a disclaimer telling people that it's out of date and improvements are welcome.

[Mikolaj]

IMHO we totally need this, in particular to justify design/implementation decisions so that future generations know something was not done by accident and there are no revert cycles as people try to fix according to different guesses as to what the intended design is.