Re: Generating the ChangeLog files from the commit messages

[David Engster]

Stefan Monnier writes:
>> I'm all for it. My hope is that this is the first step in getting rid of
>> the Changelog format altogether, and switching to commit messages that
>> value content over form.
>
> I'm not sure what other format you have in mind which would have
> better content.

That's easy: prose. Just browse through projects like Git or Linux,
which enforce meaningful commit messages. I'm interested in the 'Why'
and 'How', not in the 'Where' and 'What'.

> FWIW, I think an ideal commit message should look like:
>
>     <location-summary> <change-summary>
>     <explanation-if-needed>

Unless it's a trivial change, it's always needed. Even when you have a
bug report, at least a copy&paste of the relevant bit should be there,
so you can quickly see the problem without having to look it up.

>     <bug-nb-if-applicable>

Sure.

>     <changelog-style details>

That's precisely what I'd drop. It's just a verbose diff. I'm not saying
it's completely useless (although it comes close), but it's not worth
the effort.

> In most cases, the explanation will be empty because the bug-nb provides
> the explanation or because the explanation can be placed in the code
> instead (a better choice, when applicable).

I disagree. Comments and commit logs are orthogonal. A comment helps you
understand how code works. A commit log describes why code was changed
(unless it's new, but that's less common).

-David