On Sep 2, 2009, at 12:10 PM, David Kilzer wrote:
On Wednesday, September 2, 2009 at 8:14:14 AM, Adam Roben <aro...@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
_______________________________________________
webkit-dev mailing list
webkit-dev@lists.webkit.org
http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
