[webkit-dev] Proposal: Commit messages should start with a one-line summary of the change

[Adam Roben]

On Jun 30, 2011, at 5:10 PM, Mark Rowe wrote:

> Most ChangeLog entries already have a one-line summary immediately after the "Reviewed by" line.  I'm not sure that there's any benefit to reordering these parts of the ChangeLog.

Most ChangeLog entries have the bug title after the "Reviewed by" line, like this one: <http://trac.webkit.org/changeset/90156/trunk/LayoutTests/ChangeLog>. As I said in my email:

>> Our commit logs usually include a bug title, but the bug title only tells you about the problem, not about the solution.

I don't consider the bug title and the one-line summary I'm proposing to be equivalent. I'm also not proposing moving the bug title above the "Reviewed by" line.

>> Given this format, commit-log-editor will put the summary right at the top of the commit log. webkit-patch will require modifications to do this correctly, as represented by <https://bugs.webkit.org/show_bug.cgi?id=26755>.
> 
> commit-log-editor already does the right thing given our current format.  It's just that many people have switched to using webkit-patch, and it was never taught the correct format for commit messages.

commit-log-editor will do some wacky things that sometimes end up with the bug title and URL lines first, followed by the "Reviewed by" line. <https://bugs.webkit.org/show_bug.cgi?id=27754> seems to be the source of the wackiness. This was added in an attempt to make our commit messages work better with our tools, but doesn't help people who are browsing through ChangeLogs. I also think it's confusing that our commit messages and ChangeLogs don't follow the same order (as Adam Treat mentioned in <https://bugs.webkit.org/show_bug.cgi?id=27754#c6>).

Having the bug title on the first line (as commit-log-editor currently tries to do) is better than having the date/author line first from a tools perspective. But I think having a one-line summary first would be even better. And I think it would be nice to have the ordering of our ChangeLog entries and commit messages match.

-Adam