[Twisted-Python] Review process, news fragments

[Glyph Lefkowitz]

On Jun 19, 2010, at 6:08 AM, exarkun at twistedmatrix.com wrote:

> In particular, I'd like to draw everyone's attention to the requirements 
> for news fragments.  Since we introduced this part of the workflow, the 
> review requirements for these has been a little unclear.  Many reviewers 
> haven't required that the news fragment be reviewed (that is, if it was 
> missing, they would say "Please add a news fragment and then merge.") or 
> haven't kept the guidelines these files in mind when reviewing them.

Can you point to some specific examples in the current release, and note what they should have been?

> I'd like for this to change.  Informative, consistently written news 
> fragments result better information being available to users when we do 
> a release.  This is a very simple part the development process but 
> effort here has a disproportionately large effect on the perception of 
> Twisted.

Generally speaking, I agree.  But I think we need to nail down a very specific proposal if this is to improve.  What should reviewers be looking for in a good news fragment?  What are pitfalls to avoid?  Asking reviewers to look at something that isn't clearly spelled out may just result in more churn in reviews; I'd hate to see an extra round trip on a ticket because of an oxford comma placement in the news fragment.

> If the guidelines for news fragment content on the review process wiki 
> page are unclear or insufficient, please complain and we can work on 
> improving the weaknesses.

There's very little in the way of stylistic guidance on this page.

For one thing, I suspect there were a lot of fixes which could have been a '.misc' but were instead a '.feature' or '.bugfix'.  We need some better guidelines for what exactly constitutes a change that is interesting to users.

It advises that a single sentence be written about a change to an FQPN.  This is hard to do well for new features.  For example, "twisted.internet.endpoints now ... exists" doesn't really scan, and doesn't really emphasize the importance of the feature relative to some of the other small fixes which have been added.  I feel like I probably wrote too much of a dissertation in 1442.feature and not enough of a description in 990.feature, but I don't know what would have been better.  If you know something should be a highlight, how should that be indicated?  Should the highlight text be different from the news fragment text?

For complicated bugfixes it's also sometimes awkward, because it's hard to briefly describe a subtle, but still potentially important change in behavior.

A list of 10 examples of "good" feature descriptions and "good" bugfix descriptions would go a long way towards improving this.

Thanks for raising the issue though.  I would also like to see a more coherent NEWS file for 10.2 :).

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20100620/5b89dc61/attachment-0001.html>