On Wed, Mar 21, 2012 at 4:18 PM, Timothy Hatcher <timothy@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