Re: Should we restore manually maintained ChangeLogs

[Andy Moreton]

On Mon 07 Mar 2016, John Wiegley wrote:

>>>>>> Eli Zaretskii <address@hidden> writes:
>
>> But the discussion is not the main issue. We should actually go back to
>> having an actively maintained ChangeLog file in the repository, something we
>> stopped doing a year ago. If there's agreement to that, I rest my case.
>
> OK, let's shift this discussion in that direction again.
>
> Given that there are active developers who appreciate and use the ChangeLog
> format, I don't think we are going to remove them just yet. Instead, the
> question has been raised as to whether we should go back to maintaining
> ChangeLog files manually, or continue to generate them from version control as
> we do now.
>
> My vote is to continue generating from version control, and Eli would like to
> go back to direct maintenance. What do others think?

I have no opinion on whether the ChangeLog file should exist in the
repo, but having git commit messages look like ChangeLog entries is
actively harmful.

Most of the content duplicates what the version control system can show
you with greater accuracy, and describes only what was changed. Far too
little attention is given in this format as to *why* a changeset was
committed.

Commit messages should show both what motivates the need for a patch
(bugfix, new feature etc), and why the approach chosen is better than
other possible designs.

The Linux kernel documentation has a good description of what is needed
in a commit message in section 2 of Documentation/SubmittingPatches.

    AndyM