[webkit-dev] Changes to prepare-ChangeLog

[David Kilzer]

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.)

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.

Regarding the ChangeLog header (the line with the date, name, email address), I'm assuming two things:

1. This header is removed from the commit log entry if there is only a single ChangeLog involved.  (I think commit-log-editor used to work this way, but I'm not sure anymore.  bugzilla-tool has never had this feature to my knowledge.)

2. The common parts (the "headline" and "byline"; and sometimes the short description) are extracted from within each ChangeLog entry when there is more than one so that they appear at the top of the commit log with subsections appearing below.  (commit-log-editor does some mangling of ChangeLog entries now, but I think the formatting could still be improved.  bugzilla-tool simply concatenates all the ChangeLog entries together today.)

Dave