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

[Eric Smith]

On 05/09/2011 03:17 PM, Guido van Rossum wrote:
> On Mon, May 9, 2011 at 11:36 AM, Ned Batchelder <ned at nedbatchelder.com> wrote:
>> On 5/9/2011 1:24 PM, Terry Reedy wrote:
>>>
>>> A commit (push) partition time and behavior into before and after (with a
>>> short change period in between during which behavior is undefined).
>>>
>>> Some commit messages have the form 'x does y'. Does 'does' mean before or
>>> after? Sometimes that is clear. 'x crashes' means before. 'x return correct
>>> value' means after. But some messages of this type are unclear to me as
>>> written.
>>>
>>> Consider 'x raises exception'? The temporal reference is obvious to the
>>> committer but not necessary to everyone else. It could mean 'x used to
>>> segfault and now raises a catchable exception'. There was a fix like this
>>> (with a clear message) just today. It could also mean 'x used to raise but
>>> now return an answer. There have been many fixes like this.
>>>
>>> Two minimal fixes are 'x raised exception' or 'make x raise exception'.
>>>
>> I've always favored "X now properly raises an exception."
> 
> While my own preference is "make X properly raise an exception" I'm
> happy with any of the alternatives proposed here, and grateful to
> Terry for calling this out. Checkin comments of the form "X does Y"
> are ambiguous and confusing. (Same for feature requests in the
> tracker.)
> 
> I'm curious where the habit to use the present tense comes from; I
> wonder if it originates in some agile development practice?
> 

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.

Eric.