Recommendation for the procedure to add platform packages

[Ian Lynagh]

On Fri, Aug 21, 2009 at 08:58:56PM +0100, Duncan Coutts wrote:
> On Fri, 2009-08-21 at 02:23 +0100, Ian Lynagh wrote:
> > 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:
> 
> The policy is significantly less prescriptive than the example might
> lead you to believe.

Looking again at AddingPackages, I think you are right. That said, if I
were making a proposal, I would probably base it on an example (or a
template, which is essentially the same thing).

The AddingPackages page confuses me. If I need to read all the notes,
then the page seems very hard to read, and if I don't then could the
rationale be put on a separate page? Also, the [note-1.3]s could all be
[rationale] or [rationale-1.3], right? That way I wouldn't think that I
have to read them unless I am actually interested in the rationale.
Currently the page looks daunting to me.

> I should also note that I'm happy to improve my tar proposal to pick up
> some of the points you make. In addition to being an example proposal I
> intend to submit it as a real proposal, so improvements benefit both the
> real proposal and the example.

I've made an alternative proposal for the tar package here:

http://trac.haskell.org/haskell-platform/wiki/Proposals/alternate_example

I've made up some of the answers, and also just taken most of the
suggested requirements to be the package requirement list.

(That the trac colour scheme means that some of the hyperlinks are hard
to identify, but we can sort that out somehow).

I would be interested to hear people's opinions on how they compare.

> >     This is a proposal for the 'tar' package to be included in the next
> >     major release of the Haskell platform.
> > 
> > Should specify version number.
> 
> I expect that usually the exact number is not especially relevant. The
> exact released version now is not necessarily the same as the final one
> that gets included in the case that reviewers make suggestions.
> 
> If there's more than one active branch then yes it's relevant so
> reviewers know which one to look at. Otherwise reviewers can reasonably
> assume the version on the hackage page.

I don't see the harm in giving the intended version number in the
proposal.

It may be that 1.18 is originall proposed and 1.20 ends up being what
goes into the next release, if the changes are either following the
decisions made during the discussion, or small enough that the release
team would happily automatically upgrade 1.18 to 1.20 between two major
releases.

> The policy allows the info to be inline in the proposal or linked to.

Right, I saw that, but I think it should be /required/ to be a link.

> >     Introduction to the API
> > 
> > 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.
> 
> If we add that as a package requirement then it would be reasonable to
> change the advice to say simply to link to it. Currently the only doc
> requirement we've put in is:
> 
>         Library packages should have Haddock API documentation for all
>         exported functions and types.

I didn't mean to give an opinion on whether or not an intro to the API
should be required or not, but:
* if it is required then I think it should be linked to
* if it isn't then I certainly don't think the proposal should have to
  include one (because then there would be no reason not to require that
  it exists).

Based on our earlier IRC discussion:

<Igloo> So is the API intro in the haddock docs?
<dcoutts> yes
<Igloo> OK, ta
<dcoutts> that's where I copied most of the stuff in the proposal from
<dcoutts> but re-edited, hopefully to be better
<dcoutts> I also left out detail to make it a shorter and easier intro

it sounds to me like this is an example of exactly what I wanted to
avoid. You've spent some time making a nice friendly introduction to the
tar API, but in 6 months time when someone comes to use the tar package
they won't find this documentation, as it only exists in a "package
addition" proposal buried on the haskell-platform wiki. If you're going
to go to all the effort of making an API intro, you ought to put it on
the package's homepage.

> I expect once we've agreed the procedure that we'll get onto more
> discussing more detailed requirements on things like documentation.

Drifting off-topic, but I think that the two discussions are orthogonal
(i.e. we could have them in either order), but the "detailed
requirements" discussion is the more important one. People can make
proposals without a process being nailed down (and that may even help us
work out what the process should be), but how can we decide if a package
should be included if we don't know what the acceptance criteria are? So
I think the other discussion is much closer on the critical path.

> > 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.
> 
> The guidance notes say:
> 
>         Of course, if you end up making something new for the proposal
>         then it'd be great to keep it somewhere so that new users can
>         benefit from it too. The obvious place is in the Haddock docs,
>         or a project website.

Yes, and people will honestly intend to merge the changes and new docs
back while they are writing them. But 90% of the time they won't.

> >     Open issues
> > 
> > This is the interesting bit of the proposal, IMO. What I want to see for
> > a proposal is just something like:
> 
> That's a quite different kind of thing from what the open issues section
> is intended for. The policy says:
> 
>         Open issues and objections raised by reviewers should be tracked
>         on the proposal wiki under a separate section. [note-3.2]
> 
> and
> 
>         An explicit checklist of the package requirements below is not
>         required.
> 
> What you're asking for is a checklist.

Yes indeed. As in my example:

http://trac.haskell.org/haskell-platform/wiki/Proposals/alternate_example

> That idea was particularly
> controversial within the steering committee and it was not adopted.
> Personally I was weakly in favour if a checklist but the concerns were
> that it restricted the arguments and explanations that the proposal
> author could make. The consensus was for a much more free-form proposal
> rather than forcing things into a checklist.

For items that benefit from free-form text, you can link to a section
beyond the checklist, as in my example. Where there would no benefit, a
simple "Yes" in the table suffices, and doesn't waste any reviewer time.

> > 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 think that would come under the complaint that that is too narrow for
> the argument for why the package should be included.

I don't understand what you mean by that.

> > 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).
> 
> My concern if this is the main focus of discussions is that it covers
> the "does it work" aspect reasonably well, it doesn't cover the "is it
> any good? how could it be better?" aspects.

You can have an "Any API issues?" question, which if the answer is not
"No" will link to one or more free-form text sections. But if the answer
is "No" then it's clear at a glance that it is no. Much like the "Other
issues" item in my example.

>         The standard of consensus required is the same as that defined
>         for the existing library submissions process. [note-5.4]
> 
> Our early draft simply said that and nothing else. Several members of
> the steering committee and others who read drafts were unsure or
> unconvinced that consensus would be a usable method. We agreed to try it
> and see if it works. In addition we added the option to use this
> consensus protocol.
> 
> You will notice that in the simple case there is essentially no
> formality at all:
> 
>         The first stage is presenting the proposal followed by open
>         group discussion. This stage lasts long enough to give everyone
>         the opportunity to send in their review comments. There follows
>         a call for consensus.

In fact, I think that's the main problem I have with both the process
document and the example proposal: They try to anticipate all questions
that might be asked, and answer them. But the common case is that the
question wouldn't be asked, so this is just more stuff for someone to
write, and and more stuff for many people to read.

That's why here:

> I agree that what I've written for the rationale for the tar proposal is
> of somewhat dubious utility. In fact personally I don't like the term

you've had to write stuff "of somewhat dubious utility": because you're
answering a boilerplate question that didn't need asking in this case.

And in the case of consensus, I don't think we need to lay down rules
now for what happens if the current system doesn't work. For one thing,
it hasn't been an issue so far. For another, when we have the first case
of it not working, it might be clear that the solution would be to do
something else anyway.

> What are you suggesting specifically that would reduce the amount of
> work for reviewers?

I am suggesting that there be less text written.

> Would those things increase work for the proposal
> authors / package maintainers?

It should reduce work for the authors / package maintainers.

> Would those things increase or decrease
> the level of depth/quality of review and decisions?

I believe it would increase the number of reviewers, giving better
decisions.


Thanks
Ian