Contribution vs quality, and a few notes on the Platform process

[Gregory Collins]

On Tue, Nov 9, 2010 at 12:18 PM, Simon Marlow <marlowsd at gmail.com> wrote:
> I admit that balancing the responsibilities of the maintainer with the
> demands of the community could be tricky.  We don't want it to be a
> one-sided affair where the maintainer has to fix all the bugs while
> accommodating every demand from the community to change APIs.  So presumably
> the expectation would be that the maintainer also devolves some of the
> responsibility for maintainership to the community too - there would be some
> benefit to being in the platform, more eyes on the code.

Hi all,

Personally I would be fine with that, providing there was a plan towards a
community effort to improve the libraries we've *already approved*. To subject
maintainers of candidate libraries to the "scanning tunneling electron
microscope" while remaining oblivious to the huge usability/documentation
problems in our grandfathered libraries --- I'm looking at you, regex-*, HTTP,
old-*, QuickCheck, OpenGL, html, xhtml, pretty, etc --- isn't fair in the
slightest and is going to discourage people from submitting libraries in the
first place.

When a library is already several standard deviations above the average quality
level (like text clearly is), going over it with a fine-toothed comb and
engaging in endless rounds of proposals, counter-proposals, objections, +1s,
-1s, calls for consensus, etc. would be enough to cause even the most patient
of people to tear their hair out.

Re: improving those grandfathered libraries: I think we could probably agree
that we would like every platform library to have the following properties:

  * continuous builds either with buildbot or something like hudson (a personal
    fave)

  * automated test suites with a high level of code coverage

  * haddocks for every function, with clear examples, as well as some
    "overview" text at the main haddock page as well as at the top of every
    module containing:

      - a description of what the library *does*

      - clear and complete examples showing how it is intended to be used

    "Check out this paper from 1997" doesn't cut it. Examples of this
    phenomenon are easy to find, I found these in less than a minute of
    searching:

      - http://hackage.haskell.org/packages/archive/pretty/1.0.1.1/doc/html/Text-PrettyPrint-HughesPJ.html

      - http://hackage.haskell.org/packages/archive/xhtml/3000.2.0.1/doc/html/Text-XHtml.html

      - http://hackage.haskell.org/packages/archive/syb/0.1.0.2/doc/html/Data-Generics.html

    This is when libraries have any overview text *at all*. Examples of
    libraries in the platform with *no* introductory documentation are easier
    to find than those with good or even acceptable docs.

  * sane APIs without gratuitous "typeclass abstraction explosion"

Maybe we should assemble a posse of volunteers, divide up the libraries, and
spend a few hours each adding this kind of documentary material to try to make
a real impact on the average quality level in the platform. The cynic in me,
however, suspects that the willingness to do this kind of grunt work is greatly
overshadowed by the appetite to engage in endless rounds of mailing list
bickering.

G.
-- 
Gregory Collins <greg at gregorycollins.net>