[Python-Dev] Commit messages: please avoid temporal ambiguity (original) (raw)

R. David Murray rdmurray at bitdance.com
Tue May 10 15:33:13 CEST 2011

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

More information about the Python-Dev mailing list