[webkit-dev] ChangeLogs

[Dirk Pranke]

On Wed, Mar 21, 2012 at 4:18 PM, Timothy Hatcher <timothy at apple.com> wrote:
>
> On Mar 21, 2012, at 3:14 PM, Dirk Pranke wrote:
>
> 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 find the comments useful, even for scripts. ChangeLogs for tests are often
> more mundane.
>

I should clarify that I do find value in describing the why of the
change, so I could agree w/ Maciej that requiring *something* more
than the subject + bug + reviewer might be justified for changes. Just
linking to a bug would be overly terse.

My annoyance with ChangeLogs stems from just integrating them into my
workflow (which often involves multiple pipelined changes and/or lots
of merging and rebasing), but that's off-topic for this thread. I am
also sometimes annoyed by ChangeLogs when a change happens to span
multiple ChangeLogs and I either have to repeat myself or figure out
how to split my description between the files, which is slightly more
on-topic.

Mostly I just don't want there to be a lot of boilerplate or noise in
the ChangeLogs.

-- Dirk

> My particular interest is the Web Inspector, which I follow by watching bugs
> and commits. Often I find myself asking "why?" or "what does this do?" when
> perusing the commits. It sometimes isn't very obvious and a nice concise
> description in the ChangeLog would help. This is even more important when
> folks are separated by timezones or are not easy to reach for explanation.
>
> They also provide insight when looking back on changes from months or years
> ago when tracking down a regression.
>
> 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).
>
>
> It would be difficult to make the tool smart. I merely looking for reminder
> to push folks to describe their changes in some fashion, not a analytical
> tool parsing for good vs bad.
>
> — Timothy Hatcher
>