On Mar 21, 2012, at 3:14 PM, Dirk Pranke wrote:
On Wed, Mar 21, 2012 at 2:33 PM, Maciej Stachowiak <mjs@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 agree that setting the right conventions, and getting agreement on this, is the most important step. I think the ChangeLogs that are most worrisome are the ones that do not even have an explanatory paragraph at the top, just a bug URL and title. It can be hard to understand the I often really appreciate ChangeLogs with file-by-file or even function-by-function explanations, but I wouldn't say that is the bare minimum required for all changes. For simple changes, a short paragraph above may be totally sufficient. It is very rare that just the bug URL and title are sufficient, though. Regards, Maciej