Recommendation for the procedure to add platform packages

[Duncan Coutts]

Ian,

You raise a number of points. I'll address the easy ones here and
summarise the others in a separate email.

What I've left out is:
      * the issue about whether things should be in the proposal or
        should be required to exist as separate documents that are
        linked from the proposal.
      * the issue of a checklist / status table in the proposal

Summary of the bits where I think we already agree:
      * use [rationale-1.3] links rather than [note-1.3] for better
        clarity
      * suggest the proposal mention the package's version number
      * the 'tar' example could be improved and shortened

On Sat, 2009-08-22 at 01:17 +0100, Ian Lynagh wrote:
> 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:
> > > 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,

It is not essential to read them to be able to understand the policy.
They are there to answer the question "why was this requirement
included?" and possibly also to clarify the meaning by stating the
intentions.

> then the page seems very hard to read, and if I don't then could the
> rationale be put on a separate page?

A separate page would make it much slower to jump back and forth between
the rationale and the policy.

The intro says:

      * The rationale section gives an explanation and justification for
        the policy.

Is there a wording that would make it clearer that you do not have to
read it unless you want an explanation for a point in the policy?

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

That's a good idea, we should do that.

> Currently the page looks daunting to me.

We already split off the "how to" guide into a separate page. We could
possibly do the same with the consensus protocol. I think the rationale
should stay with the policy however.

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

Right, there's no harm and it's fairly easy for the author to add that
info. I'm happy to suggest it in the "how to" guide. I don't think it's
such crucial info that it needs to be explicitly required by the policy.


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

The acceptance criteria is clearly specified. It is not that a set of
minimal requirements be met. It is that the reviewers, using their
judgement come to a consensus to accept the package.

> So I think the other discussion is much closer on the critical path.

I don't think it is on the critical path. I think it is quite possible
to start reviewing packages and try to codify what we agree additional
criteria should be. If there are significant disagreements between
reviewers while reviewing packages then these would indicate areas where
it may be helpful to codify a requirement or guideline.

There is certainly an advantage to having a more comprehensive set of
requirements and guidelines because it'll help people proposing packages
to know what to aim for and should help reviewers to agree with each
other about a package.


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

This is true, but is the balance of benefit such that we should leave
various questions open in favour of making it slightly quicker to read
the policy? I note that the policy is only 1500 words. We deliberately
tried to keep it short by separating it from the rationale and from the
practical advice.

Is there anything specific in the policy you would remove that would
make the thing appreciably shorter without making it too ambiguous? My
guess is that you'll say the consensus protocol.

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

I think it's partly that I originally wrote the example for a draft of
the policy that was significantly more prescriptive about the structure
of the proposal and I did not update it significantly when I adapted it
for the final draft.

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

That is what we had in an intermediate draft. We added the facility for
more formality in contentious cases because several members of the
steering committee and other people who read the draft expressed the
concern that despite consensus working ok for the libraries process,
that it might not work so well for deciding on package additions.

Is there any disadvantage to having this option available? Do you think
it is a bad option or merely unnecessary? Is it just the fact that it
makes the wiki page longer?

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

That option is always open anyway. The rationale says:

        [note-5.4] The exact definition of what constitutes a consensus
        is possibly a contentious point. The obvious choice is to do
        what we already do with the existing library submissions
        process. It uses a relatively vague definition of consensus and
        yet has worked reasonably well in practice. If it does not work
        out in practice for the package addition process then the
        libraries list may want to revisit this point.

> > What are you suggesting specifically that would reduce the amount of
> > work for reviewers?
> 
> I am suggesting that there be less text written.

Less text in the proposal or less text in total? You've suggested that
the proposal link to several external documents.

> > Would those things increase work for the proposal
> > authors / package maintainers?
> 
> It should reduce work for the authors / package maintainers.

Even taking into account that you would expect them to write these
external documents? Where is the reduction coming from?

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

I'm afraid I'm not clear about where the reduction is coming from in
what authors / package maintainers have to write and reviewers are
expected to read. Is it just the "rationale waffle" stuff from the 'tar'
example that you mean?

Duncan