On Sun, Dec 2, 2012 at 6:19 PM, Jeff Allen <"ja...py"@farowl.co.uk> wrote:

On 02/12/2012 07:08, Nick Coghlan wrote:

On Sun, Dec 2, 2012 at 4:56 PM, christian.heimes < python-checkins@python.org> wrote:

...

... http://hg.python.org/cpython/rev/9af5a2611202 diff --git a/Misc/NEWS b/Misc/NEWS ...

+- Issue #16592: stringlib_bytes_join doesn't raise MemoryError on allocation + failure.

Please don't write NEWS entries in past tense like this - they're annoyingly ambiguous, as it isn't clear whether the entry is describing the reported problem or the fix for the problem. Describing just the new behaviour or the original problem and the fix is much easier to follow. For example:

- Issue #16592: stringlib_bytes_join now correctly raises MemoryError on allocation failure. - Issue #16592: stringlib_bytes_join was triggering SystemError on allocation failure. It now correctly raises MemoryError.

Issue titles for actual bugs generally don't make good NEWS entries, as they're typically a summary of the problem rather than the solution (RFE's are different, as there the issue title is often a good summary of the proposed change)

You mean please do (re-)write such statements in the past tense, when the news is that the statement is no longer true.

I agree about the ambiguity that arises here, but there's a simple alternative to re-writing. Surely all that has been forgotten here is an enclosing "The following issues have been resolved:"? I think there's a lot to be said for cut and paste of actual titles on grounds of accuracy and speed (and perhaps scriptability).

Readability matters - ambiguous release notes don't help anyone, and, like code, release notes are read by many more people than write them. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia