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

[Adam Roben]

On Jul 1, 2011, at 11:57 AM, Julien Chaffraix wrote:

>>> I don’t think it’s a good idea to add yet another thing to every change log entry.
>> 
>> I wouldn't consider this something being added. Most ChangeLog entries (the good ones, anyway) already contain a description of the fix in addition to the bug title, URL and reviewer.
> 
> While I sympathize with the idea of the one line explanations, I think
> this adds unneeded complexity to our workflow and the added value you
> mentioned does not seem to overcome it (namely making a couple of
> tools work better).

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

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. (Note that our current ChangeLog template doesn't say that you should include *any* description of the change.)

-Adam