[webkit-dev] Changes to prepare-ChangeLog

[Maciej Stachowiak]

On Sep 1, 2009, at 12:59 PM, Adam Roben wrote:

> On Jul 9, 2009, at 4:32 AM, Maciej Stachowiak wrote:
>
>> How about this as the canonical format (with prepare-ChangeLog  
>> encouraging it)?
>>
>> 2009-07-08  Maciej Stachowiak  <mjs at apple.com>
>>
>>       Make prepare-ChangeLog less shouty
>>       https://bugs.webkit.org/show_bug.cgi?id=27098
>>
>>       Reviewed by Mark Rowe.
>>
>>       * Scripts/prepare-ChangeLog:
>
> This format seems good when the patch in question actually fixes the  
> bug. But in cases where a bug requires multiple changes to be fixed,  
> I find this format confusing. For example, here's the top of the  
> ChangeLog from r47943 <http://trac.webkit.org/changeset/47943>:
>
>> 2009-09-01  Brady Eidson  <beidson at apple.com>
>>
>>       Reviewed by Sam Weinig.
>>
>>       Page Cache should support pages with frames
>>       https://bugs.webkit.org/show_bug.cgi?id=13631
>
> When I saw this, I assumed that r47943 was changing WebKit/WebCore  
> so that the page cache would support pages with frames. But it turns  
> out that r47943 was just one step along the path to making that  
> happen.
>
> What I like to do in cases like this is to start the ChangeLog with  
> a short description of what *this patch* does. Here's an example  
> (from r44269 <http://trac.webkit.org/changeset/44269>):
>
>> 2009-05-29  Adam Roben  <aroben at apple.com>
>>
>>       Make sure PlatformMouseEvent::modifierFlags contains MK_ALT  
>> when the
>>       Alt key is pressed
>>
>>       First part of fixing Bug 25729: Alt-clicking a link doesn't  
>> start a
>>       download
>>       https://bugs.webkit.org/show_bug.cgi?id=25729
>>
>>       Reviewed by Darin Adler.

I think the bug title and URL should be above the brief description of  
what this particular patch does. I don't like the bug URL being so far  
down.

>
> (You can ignore the "First part of fixing Bug 25729: " part -- I  
> know some people dislike that and I'm not advocating it as part of  
> this email.)
>
> So, I propose that we change the prepare-ChangeLog template to the  
> following:
>
> 2009-09-01  Adam Roben  <aroben at apple.com>
>
>        Reviewed by NOBODY (OOPS!)
>
>        Need a short description of this patch (OOPS!)
>
>        Need a bug title and URL (OOPS!)
>
>
> What do others think?

I'd swap the last two. Maybe we could make the bug URL nag say "Need a  
bug title and URL - if a partial fix please say so (OOPS!)"

Regards,
Maciej