[webkit-dev] Proposal: Commit messages should start with a one-line summary of the change

Julien Chaffraix jchaffraix at webkit.org
Fri Jul 1 09:57:59 PDT 2011

> I wasn't trying to add any complexity. My hope is that people are already adding descriptions of their changes to their ChangeLog entries, like you do. I was just trying to suggest a better way to organize that description.
> In my original email I noted two benefits of making this change:
>>>>> 1) It would make it much easier to understand at a glance what the change actually does.
>>>>> 2) It would make many of our tools work better

Thanks for clarifying here. I would have equated 1) to the very
existence of ChangeLog which is supposed to give this background.

> I see (1) as the primary benefit, and (2) as a nice side-benefit.
>> Also you are implicitly constraining people to explain their change
>> with one-liners which IMHO is not a good constraint. I would rather
>> see good explanations than explanations that need to match a format.
> I'm not trying to constrain descriptions to one line. I think that would be horrible in a lot of cases! I'm just suggesting that there be a one-line summary at the top followed by a more detailed description below.

I said that it _implicitly_ added a constraint. Let me take an example
to make this point clear: if you have a 1.5 line long description, it
doesn't seem to make sense to split it in 2. I, maybe other people
too, would side with removing maybe important information for
shortness's sake. This sounds like the kind of case where the strict
format is harmful. It may be theoretical but it looks like a slippery

> (Note that our current ChangeLog template doesn't say that you should include *any* description of the change.)

Indeed and I agree with you that this is wrong. However my feeling is
that reviewers usually asks for that information to be included as
part of the ChangeLog if it is not present.

My argument is against the format I would say, not about making this
information available / mandatory.


More information about the webkit-dev mailing list