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

[Duncan Coutts]

On 9 November 2010 12:02, Gregory Collins <greg at gregorycollins.net> wrote:
> 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*.

Absolutely. We need to work on how to do this, checking what areas are
not up to scratch, defining what "up to scratch" means.

> 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.

Yes. It is a fair criticism and the solution is to improve the existing libs.

A combination of individual package maintainers and teams that work
across multiple packages might work.

> 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.

Though one outcome of these discussions is to establish what standards
and principles the community thinks are important. It should also
embarrass us into applying the same standards to the existing libs.

We deliberately avoided having a long abstract discussion about
standards before getting on with the first proposals, which had the
downside that we've been working on both simultaneously for the first
reviews. The steering committee has also been a bit derelict (mea
culpa). Hopefully with some tweaks things will be smoother in future.

> 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)

Yep, or if the hackage-server / cabal-install build bot system works
soon enough then we can use that. We were working on that at the
hackathon the other day. We could use this system before we do the
switchover of the main hackage.haskell.org site, indeed we want to use
a separate testing server instance anyway.

>  * automated test suites with a high level of code coverage

Cabal-1.10 now has support for testsuites. We need to add hackage
reporting and an HPC coverage feature.

>  * 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:

[snip]

Agreed.

>  * 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.

Yep. It helps enormously to know you're working in a team on this kind of thing.

> 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.

Don started on it the other day at the hackathon.

Duncan