[webkit-dev] ChangeLogs

[Maciej Stachowiak]

On Mar 21, 2012, at 3:14 PM, Dirk Pranke wrote:

> 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 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