[Python-Dev] Commit messages: please avoid temporal ambiguity

[R. David Murray]

On Tue, 10 May 2011 22:29:58 +1000, Nick Coghlan <ncoghlan at gmail.com> wrote:
> On Tue, May 10, 2011 at 5:36 AM, Eric Smith <eric at 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