Russ: On Fri, Jun 26, 2009 at 2:14 PM, Russ Allbery<[email protected]> wrote: > Jonathan Yu <[email protected]> writes: > >> I agree that Policy should be kept a closely reviewed thing. But maybe >> we can have something like AnnoCPAN, where users are allowed to >> provide /annotations/ inline with the actual policy. So people can add >> things like "be careful here, this means ..." or something. >> >> Then those annotations can be considered proposed changes for the >> future, and the Policy folks can look through that to integrate things >> (like clearer wording) into the actual, official Policy. >> >> It is, I suppose, somewhere between a full wiki and the current >> protectionist measures :-) > > My concern is that, as you can see from the open bug list, we already > have a review bandwidth problem. I'm not sure making it easier still to > propose changes is going to help much. We need to get better at making > changes. That is a very good point. I imagine that there are much more things proposed than there are people to properly review them and 'vote' on them. (well, to the extent that seconding things counts a vote) > > The hard work is taking a proposal for a concrete change, thinking > through all the implications, getting buy-in from the affected people, > and then writing a section of Policy for it that clearly communicates > the issue. Secondarily, we need more reviewers after people do produce > language, although that's gotten much better than it was. How does one go about volunteering to review the policy wording? I'm a native English speaker so I could try my hand at making sure the Policy remains unambiguously and helpfully worded :-) It is thankfully in a pretty good state right now, and that couldn't have been easy. > > Proposing changes is the easy part. If we make that part even easier, > we're going to end up with even more of a backlog. The idea of something like AnnoCPAN isn't solely about proposing changes, it is also about being able to add things like: this section was a bit confusing, here's an example to explain what it means.
The nice thing about a separate Annotated Policy document is that people have the choice of either reading the normal one (ie, like the normal CPAN documentation) or reading the annotated one, which might contain some useful help or discussion, but which is known to be non-official. So the Debian Policy Manual remains an authoritative document. > > Note that wording changes that don't change the dictates of Policy, such > as are discussed on this thread, any Policy maintainer can just make if > they agree. I'll be committing something from this thread shortly, for I've noticed you've made a few changes in terms of cleaning up wording, so thanks very much for that. > instance, once people have had a chance to look at the new wording, and > similar to how I just committed something for the Installed-Size > discussion. These are fairly easy. It's the changes to what Policy > requires that take the time and effort. I think it's admirable that the Debian Policy maintainers have achieved a good balance of sufficient discussion of big things, while also avoiding the whole bikeshed argument problem. It seems that productive work gets done with only a few back-and-forth messages with no serious disagreements, which is great. > > As a Policy maintainer, I would much, much rather that wording changes > be given in the form of a diff that I can apply than in the form of an > annotation that I have to do more work to get into the canonical > document. That saves me time and lets me spend more time on the hard > problems. If it's a particularly serious patch, but merely a little gotcha, people are less likely to submit a diff. That's what something like an annotated policy is all about. For example if someone reads a section but doesn't understand it completely on the first read, and needs to re-read it a few times, they will probably not submit a patch. But, other people might benefit from having an example to illustrate what is meant by that paragraph, or something. This is somewhere where an annotated manual might help. I don't think we'll run into any issue of developers considering that manual *authoritative*, but it would be nice for casual developers to drop arbitrary hints in there. For example, the Vcs-* fields are currently not in policy, though they are discussed in the developers' reference. That set of fields is being discussed right now, so it doesn't yet belong in policy, but perhaps an annotated policy could mention "the Vcs- fields are currently a bit of an ad-hoc standard, but not yet a part of the general Debian policy." etc. I definitely see your point though, and I agree that we want to avoid creating too much extra work for the Policy maintainers, especially if there is no real perceived advantage. In that respect, I would love to volunteer some of my time to possibly re-wording things in the Policy to make them clearer and easier to understand for all. Cheers, Jonathan -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected]
