Broken documentation on Hackage.

[Mateusz Kowalczyk]

Hi all,

It seems that we are having a rather big issue with Hackage in recent
months and I'm sure many of you have noticed: a lot of packages aren't
getting their docs built. As far as I can tell, there can be multiple
reasonable causes:

* Dependencies fail to build so your package does
* Your package fails to build directly
* Your package requires non-cabal libraries which aren't installed
* Your package requires different version of install libraries

While all of these are understandable, there also seem to be problems
with some packages which are seemingly perfectly fine otherwise. This
problem is not new and has been reported[1]. There is even a system in
place with Hackage 2 that would grant package owners to manually upload
documentation and a system where some people (trustees and package
maintainers) have the ability to do things like deleting the broken docs
to have the builder try again[3] but it seems that this isn't actually
used[4].

Over night I hacked up a quick program to parse some Hackage parts to
see just how much stuff was broken. I have only considered the most
recent package versions. Out of the 7761 packages, 811 came up with
missing documentations. While it is a big number (~9.56%), it includes
every package on Hackage. Next thing that follows is to restrict the
search a bit. Only considering packages from 2013 and the still very
young 2014, 210 are missing documentation. 140 of those were uploaded
since August 2013 (around the Hackage 2 move). Remember that this is
only for most recent versions on Hackage. Assuming that we didn't have a
large spike in package uploads in second half of 2013 (I don't know, are
there any charts or something?), that's unreasonably more than in the
first half of 2013.

It should be fairly clear that something is broken and I'd love to know
what. I snooped around in #hackage today for a bit and there doesn't
seem to be much sense of the urgency. Granted, people are busy but isn't
this a pretty important issue? It's not like it's recent either.

What can we do? Why isn't it fixed? Are there any suspects? Why isn't
the trustee system being used to mitigate this problem a bit while it's
being fixed? Is there any way to improve the amount of things that can
be built by trying to work out any of the points at the top of this
e-mail? Honestly, scrolling through the build logs of packages, all
failures seem reasonable (Haddock parse failure, no dependencies
installed…) and yet somehow I find myself having to click on older
version of packages to get docs very often recently. What changed? Is
there even anything to fix? Maybe I'm just getting unlucky with the
packages I click on recently.

I have uploaded the list of packages with missing documentation that
have been uploaded on Hackage in 2013 and 2014 to [5]. The format is:
(packageUrl, MissingDocs (Maybe reason) packageVersion dateUploaded). If
your package is on there, you might want to consider uploading the docs
by hand for now! Packages with ‘Nothing’ for a reason have no build log.
See [6] for a reason for those. See [7] for how to view build logs yourself.

PS: I'm unsure if these are the right lists to e-mail. I've been told
that Cabal folk maintain Hackage issues and considering so many broken
docs, libraries might also be interested in it. Feel free to point me
elsewhere.
PPS: There also seems to be a lot of 404 errors while trying to click on
some docs on some older packages that probably existed in the past.
Perhaps they were lost in the Hackage move or are a different issue all
together.

[1]: https://github.com/haskell/hackage-server/issues/145
[2]:
https://github.com/haskell/hackage-server/issues/145#issuecomment-29468613
[3]:
https://github.com/haskell/hackage-server/issues/145#issuecomment-29422332
[4]: http://hackage.haskell.org/packages/trustees/
[5]: http://fuuzetsu.co.uk/misc/sorted.txt
[6]:
https://github.com/haskell/hackage-server/issues/145#issuecomment-30129142
[7]:
https://github.com/haskell/hackage-server/issues/145#issuecomment-29472445
-- 
Mateusz K.