Recommendation for the procedure to add platform packages

[Ian Lynagh]

On Thu, Aug 20, 2009 at 03:04:20AM +0100, Duncan Coutts wrote:
> 
> There is also an example proposal:
> 
> http://trac.haskell.org/haskell-platform/wiki/Proposals/example
> 
> So please send in your comments and of course feel free to ask questions

I read the example first, so I'll give my comments on it first:


My first impression is that there is an awful lot of text, and that it's
mostly in paragraph form (i.e. I need to actually read it, rather than
the key points being highlighted). I think this will reduce the level of
review that proposals get.

    This is a proposal for the 'tar' package to be included in the next
    major release of the Haskell platform.

Should specify version number.

    Review comments should be sent to the libraries mailing list by
    ${deadline - 4 weeks}

This sounds like it is the wrong way round to me. The deadline for
review comments should be "${now + 2 weeks}" (for some value of 2, and
larger values for complicated/large proposals). If you make the proposal
early, then it can be agreed earlier. If you make it too late for the
discussion and consensus to happen by the deadline then it can wait
until the next release.

(that's pretty much how library submission proposals work).

    Abstract

I think this should be replaced with a link to the hackage page, which
shows the abstract from the Cabal file. You might argue that having all
the info in one place is convenient for reviewers, but
* I am unconvinced that it is much easier
* Packages that are proposed are probably widely used anyway, so this is
  just noise to a significant proportion of people
* by only linking to it you remove the temptation to alter the text in
  the proposal but not apply the improvments to the Cabal file.

    Rationale

I don't think the actual rationale part of this section is useful. It
mostly says "The foo library is useful because some people want to foo".
If during the discussion we find that the rationale is unclear then a
rationale could be added to the proposal, but mostly I expect it will be
self-evident (and if not then the abstract in the Cabal file probably
needs some work).

The list of users is useful (less convinced by the list of packages you
think /ought/ to use it), but a bullet-pointed list would be much easier
to read.

    Introduction to the API

What I said about the abstract applies here, only moreso. If an intro to
the API is useful, then one should already exist. People should not be
given the opportunity to /write/ an introduction to the API here; it
should already be in the haddock docs on hackage, or on the project page
on community, or in some similar location. Therefore this too should
just be a link. Again, this will remove the temptation to update the
proposal but not the real docs following the discussion. It will also
mean people don't waste time reformatting docs in wiki markup.

    Design decisions

Ditto.

    Open issues

This is the interesting bit of the proposal, IMO. What I want to see for
a proposal is just something like:

    Package:                                          mylib 1.2
    Is useful?               [green] [link to below]  Yes[/link]   [/green]
    Has intro to API?        [green] [link to hackage]Yes[/link]   [/green]
    Has design decision doc? [yellow]                 No           [/yellow]
    Builds on all platforms? [green]                  Yes          [/green]
    Builds with all impls?   [yellow]                 No           [/yellow]
    Good API?                [green]                  No objections[/green]

    Is useful ("Is useful?" above links to here)
    ---------
    Users include:
    * darcs
    * tar

    Has design decision
    -------------------
    The package is too simple for such a doc to be useful. [...]

    Builds with all impls
    ---------------------
    hugs is missing the WibbleTheThingy extension, so cannot build the
    package. But H2010 will include WibbleTheThingy, so hugs is expected
    to implement it soon.

and the goal of the discussion would then be to get a consensus on
whether the yellow sections are severe enough to not accept the package
(and also to give people a chance to disagree that some of the green
entries really are green, e.g. "Is useful?" is subjective).

I've mentioned this link on IRC before, but for those who haven't seen
it, this is partly inspired by:
    http://release.debian.org/etch/arch_qualify.html
(which shows at a glance which arches are acceptable to be in a Debian
release, and where the issues and potential issues are. The link in the
first row gives more detail on some of the points).

>
> http://trac.haskell.org/haskell-platform/wiki/AddingPackages
>

I've only skimmed this, due to the length, but my impression is that it
is too heavy-weight. e.g.
    http://www.haskell.org/haskellwiki/Library_submissions
has this to say about consensus:

    If someone has done all this, they are entitled to expect feedback;
    silence during the discussion period can be interpreted as consent. 

    If consensus was achieved, [...]

and doesn't seem to have had problems with getting consensus, or
agreeing whether we have got it. The "Achieving consensus" section of
AddingPackages is 947 words according to wc (that's about double the
length of the entire Library_submissions page).

Also, the fact a credits section was deemed necessary suggests to me
that too much work is involved.



Thanks
Ian