On Tue, 10 May 2011 22:29:58 +1000, Nick Coghlan <ncogh...@gmail.com> wrote:
> On Tue, May 10, 2011 at 5:36 AM, Eric Smith <e...@trueblade.com> wrote:
> > Thanks indeed for bringing this up, Terry. It's been on my to-do list
> > for a while. I think it comes from just copying the title of a bug
> > report. The bug is "X does Y", and that's what's used in the fix.
>
> I believe I've actually seen it in NEWS entries as well (although
> thankfully not often and I can't recall any specific instances off the
> top of my head).
>
> I'm also a fan of including the word "now" and describing the new
> behaviour, although I'll sometimes use "no longer" and describe the
> old behaviour for some bugs where that seems more appropriate.
I generally don't use the same text for commit and NEWS, because I like
to stick to one-liners for the first line of the commit, possibly with
more detail in the body, while for NEWS items I'm aiming for a one to
three line description. But in both cases what I'm thinking about is
"what have I *changed*". In the commit message that will probably focus
more on code changes, while the NEWS item will focus more on behavior
changes, but the results are generally similar.
So for example my most recent two comments look like this:
commit:
11999: sync based on comparing mtimes, not mtime to system clock
NEWS:
Issue 11999: fixed sporadic sync failure mailbox.Maildir due to its
trying to detect mtime changes by comparing to the system clock
instead of to the previous value of the mtime.
commit:
#11873: Improve test regex so random directory names don't cause test to
fail
NEWS:
Issue #11873: Change regex in test_compileall to fix occasional
failures when when the randomly generated temporary path happened to
match the regex.
You will note the *active* verbs "fixed", "improve", and "change"
figure in there prominently :)
(Eh. And proofreading this email I see I made a grammar error in
that first NEWS example :(
--
R. David Murray http://www.bitdance.com
_______________________________________________
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
