Haskell Platform package additions: decision time!

[Duncan Coutts]

All,

About a month ago we came up with a recommendation for a procedure for
adding new packages to the Haskell Platform.

Initial announcement:
http://haskell.org/pipermail/libraries/2009-August/012397.html

Proposed policy:
http://trac.haskell.org/haskell-platform/wiki/AddingPackages

If you like the video format then see 7min:15sec into this talk (from
the recent Haskell implementers' workshop)
http://www.vimeo.com/6572504


We would like to get this wrapped up so that we can move on to
discussing more guidelines/requirements on packages and indeed to
actually proposing some packages.

So far we have had a few people send in comments (thanks particularly to
Ian and Simon) but a few more would not go amiss, even if it's just
"yes".


If you were following the original thread you'll remember that Ian has a
few concerns that we've not yet fully resolved. I have suggestions for
how to move forward. Feedback and opinions from other people would
probably help.

I'll set out what the concerns are and what I suggest. Two of the
complaints we can deal with fairly easily, the third would be a more
radical change from what we're proposing, but we can move a bit closer.


First the two simple ones:

Concern 1: "The policy document itself is too long and too detailed."
        
Quick poll: should we split the rationale into a separate page or keep
it on the same page? Yes or no.
        
      * Advantages: policy document looks shorter, less intimidating
      * Disadvantages: slower to jump back and forth between the policy
        and the rationale (the two are fully cross-referenced)

If we split it, then the main page would look like this:
http://trac.haskell.org/haskell-platform/wiki/AddingPackagesCore
and the "[rationale-x.y]" links would point to a separate page.

It really doesn't matter which we pick, we just need to decide and get
on with it!
        

Concern 2: "Documentation written for the proposal will get lost."

The concern here is that if people write some new intro tutorial or
something for a package proposal that this might never get integrated
into the package's documentation.

Ian's suggested remedy is to force proposals to link to existing
documentation rather than letting proposal authors make something new or
make a customised variation on existing docs.

The principle that the steering committee seemed to agree on is that the
proposal author be given the freedom to present their argument in
whatever way they see fit.

The alternative that I am proposing is this: in the case that
completely new documentation is written for a proposal, there be
a presumption that a condition of acceptance is that the new material be
republished in the appropriate place and form. For example this might
mean the reviewers require that new intro docs be integrated into the
haddock docs or perhaps as a separate tutorial or user guide on the
package's homepage. The point is that by attaching it as a condition of
the package being accepted, that we ensure that it does actually get
done rather than nice docs languishing where no users will find them.
The policy already has the facility for conditional acceptance so this
just adds a presumed condition.


Concern 3. The more major and general complaint Ian has is that he
believes the criteria for acceptance should be essentially a checklist.
Some checklist items would be objective, some subjective, but passing
them all would be sufficient for a package to be accepted. With this
approach the proposal would also essentially be a checklist, noting that
each one is met (with explanation as appropriate).

By contrast, the criteria that the steering committee proposes is that a
package is accepted if the reviewers reach consensus. That is,
ultimately it is up to the judgement of the reviewers. This approach is
augmented with a list of minimum package requirements to make it clearer
what level package authors have to aim for.

In the limit the two approaches are the same. By adding more and more
package requirements and guidelines the grey area left up to the
judgement of reviewers is reduced. Also, the checklist approach allows
some items to be essentially "do the reviewers agree that ...", so it's
still a judgement and a consensus but broken up into categories.

Related to this issue is the concern that we will find it impossible to
agree on any packages before we have agreed a more comprehensive set of
package requirements. My argument is that we can make progress on both
simultaneously, that is we can start discussing individual package
proposals while also discussing general package requirements. Indeed I
think the two discussions might inform each other. In the worst case we
get blocked discussing a package because we do not agree on the level of
some quality requirement, in which case we move to discussing general
package requirements and record the decision in the policy.

So my suggestion on this complaint is that we go with the policy that
the steering committee has proposed and that we move quickly afterwards
to discuss more comprehensive package requirements and guidelines.


Duncan