On Mar 21, 2012, at 3:14 PM, Dirk Pranke wrote: > On Wed, Mar 21, 2012 at 2:33 PM, Maciej Stachowiak <m...@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 _______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
