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-check...@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 | ncogh...@gmail.com | Brisbane, Australia
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
