[webkit-dev] Changes to prepare-ChangeLog

[Adam Roben]

On Sep 2, 2009, at 12:10 PM, David Kilzer wrote:

> On Wednesday, September 2, 2009 at 8:14:14 AM, Adam Roben <aroben at apple.com 
> > wrote:
>
>> On Sep 1, 2009, at 9:03 PM, David Kilzer wrote:
>>
>>> Not git-friendly enough, IMO.  I like this better:
>>>
>>> 2009-09-01  Adam Roben
>>>
>>>       Need a bug title and URL (OOPS!)
>>>
>>>       Reviewed by NOBODY (OOPS!)
>>>
>>>       Need a short description of this patch (OOPS!)
>>
>> I wasn't trying to make things more git-friendly with this change,
>> though I think that is a worthy goal. (If we are talking about git-
>> friendliness, then I think it's better to put the "short description
>> of this patch" on the first line, not the bug title.)
>
>
> I shouldn't even say "more git-friendly".  It's really about putting  
> the most important information first (assuming that most bug titles  
> are well-written :).
>
> IMO, ChangeLog entries should be written like good newspaper articles:
>
> - Headline first (bug number/URL and bug title).
>
> - Byline (who reviewed it; author is usually implicit in commit log  
> entry, but when a third party commits, it might be nice to include  
> the patch author in this line).
>
> - Short, succinct description of the change.
>
> - The details.  (In newspaper articles, the text of the article  
> should be written with the most important information at the top of  
> the article and the least import information at the bottom so that a  
> reader can stop at any time once they've reached their appropriate  
> level of detail.  For ChangeLog entries, the detail level is  
> probably the same for all the code changes.)

I'd argue that "Short, succinct description of the change" is more  
like a "headline" than the bug title. If newspaper headlines were  
equivalent to bug titles, we'd have zillions of newspaper articles all  
with the title "Economic Crisis".

> By writing all ChangeLog entries this way, it makes it possible for  
> people who read them to stop at the appropriate level of detail more  
> consistently.

I think that's an interesting point. I think we do want to make it  
easy to skim through ChangeLogs, only looking at the "level of detail"  
you care about. I don't think putting the short description first  
makes this any harder. For one thing, it's only a single line (though  
you could of course make the same argument in favor of putting the bug  
title first). For another, the bug title/URL are often the easiest  
thing to find in the entry when skimming, because the syntax of a URL  
is easy to spot. So I'd argue that putting the short description first  
does not make it any harder to find the bug title/URL, while putting  
the bug title/URL first *does* make it harder to find the short  
description.

-Adam