[webkit-dev] Changes to prepare-ChangeLog
aroben at apple.com
Wed Sep 2 09:23:46 PDT 2009
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
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
More information about the webkit-dev