Status and GHC's treatment of Haddock

[Ben Gamari]

Hi all,

Sadly `master` has been broken for much of the day. The causal-chain
is roughly the following:

 1. Last week a haddock merge-request was prematurely merged by a
    haddock developer, despite not being compilable, to the `ghc-head`
    branch.
 2. marge-bot failed during a merge on Sunday
 3. On Monday I finished merging the half-merged batch manually, not
    aware of the inconsistent submodule state. However,
    while doing so some unintended changes crept in, relying on 
    an unmerged haddock commit.
 4. in an attempt to fix the inconsistent submodule state another
    developer merged the unmerged commit
 5. I notice the unintentional commits on `master` and start to back
    them out
 6. I note that even after backing out the unintentional commits the
    tree *still* doesn't build due to haddock
 7. I perform a fair amount of head-scratching trying to figure out what
    is going on; eventually I find the non-building commit.
 8. I eventually sort out what needs to be backed-out and in what order

I take a few lessons from this:

 * manual merges, no matter how "straightforward", are always a vector
   for mistakes. I should have triple-checked my work before pushing
   manually pushing the half-merged branch.

 * haddock submodule changes going in prematurely come with a very high
   cost, especially if they don't build. It turns out I had run into
   the non-compilable haddock commit a few times last week but had
   chalked it up to in-flight changes.

On the whole, I am really starting to wonder whether we can't improve
our model for dealing with haddock; it is currently quite easy for haddock
and GHC to enter an inconsistent state. Moreover, the fact that
`haddock`'s `ghc-head` branch runs ahead of `master` means that we won't
realize the problem until it's too late.

One small improvement would be to move Haddock to GitLab. This would at
least ensure that there is a clear connection between haddock MRs and
their corresponding GHC changes. I have suggested this to Alex.

Beyond this, it would be great if someone could step up to finish the
hi-haddock change [1]. I suspect this refactoring has the potential to
greatly improve this situation: the interface file AST tends to be more
stable that the Core AST and has significantly less surface area. After
this is in place Haddock could then use either its own AST or a frozen
HsSyn AST from GHC (faciliated by TTG) internally, greatly reducing the
coupling between Haddock and GHC.

Any takers?

Cheers,

- Ben
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 487 bytes
Desc: not available
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20201215/9160c195/attachment.sig>