[webkit-dev] ChangeLogs

[Dirk Pranke]

On Wed, Mar 21, 2012 at 2:33 PM, Maciej Stachowiak <mjs at apple.com> wrote:
>
> On Mar 21, 2012, at 2:29 PM, Timothy Hatcher wrote:
>
> Lately I have observed more and more and more changes going into WebKit that
> lack any details about why a particular change was made. It is intended that
> the ChangeLog (and commit message) contain some details about your change,
> not just the bug title and URL.
>
> The contributing information on subject is pretty sparse, which has likely
> caused this problem to manifest. However, the example ChangeLog linked from
> that page is prime example of what we all should strive for when describing
> our changes.
>
> To help curb this lack of detail in ChangeLogs, I propose we add script (or
> augment an existing script) to check for this missing information and inform
> the contributor. It is clear not all reviewers are asking patch authors to
> provide this information when reviewing, and such a tool would help enforce
> it.
>
>
> I think this is a reasonable suggestion. I think we should make the
> contributor docs more clear about what is expected, as well.
>

I think this is a reasonable suggestion, but I don't agree with it :).
I would prefer that we try to get good changelogs through culture and
convention rather than through good tooling.

This is of course based on my experience in my changes and the types
of changes I review, but I personally find what value there is at all
in ChangeLogs in the paragraphs at the top of the change, and I find
the lists of changed files and to be distracting noise far more often
than not. (Perhaps things are different in changes to the core
rendering code than changes to tooling and test code).

I think it is difficult to say what a "good" changelog is an any sort
of algorithmic sense, and trying to implement something that would be
done programmatically will be more annoying than useful (even if it
means that I just have to delete a bunch of "OOPS" lines).

-- Dirk

> Regards,
> Maciej
>
>
>
> _______________________________________________
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
> http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
>