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

[Guido van Rossum]

On Mon, May 9, 2011 at 12:36 PM, Eric Smith <eric at trueblade.com> wrote:
> 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.

But in bug reports it is also ambiguous, since I've often seen it used
meaning "X should do Y" which is very confusing when it doesn't do Y
yet at the time the bug is created. :-(

-- 
--Guido van Rossum (python.org/~guido)