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