[webkit-dev] Changes to prepare-ChangeLog

[Adam Roben]

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.

(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?

-Adam