Re: Circumstances in which ChangeLog format is no longer useful

[Ludovic Courtès]

Hi Joseph,

Joseph Myers <address@hidden> skribis:

> On Fri, 4 Aug 2017, Alfred M. Szmidt wrote:
>
>> They cannot be generated by a computer.  Your remainder points do not
>> address how ChangeLog entries are a bad thing, rather they show that
>
> They are a bad thing because they force writing a description of a 
> changeset at a per-file, per-named-entity level, whether or not a 
> decomposition into those pieces is a good way to describe that particular 
> changeset, and because they force writing such a description that 
> concentrates on information that can readily be obtained by reading the 
> associated patch, which is the exact opposite of what a good commit 
> message should be concentrating on, namely information at the logical 
> level about the change as a whole and the reasons for it, that complements 
> the change itself, so helping the reader in understanding the patch in its 
> proper context, rather than duplicating it.

I think this part of the change log rationale still holds (info
"(standards) Change Log Concepts")

     There's no need to describe the full purpose of the changes or how
  they work together.  However, sometimes it is useful to write one line
  to describe the overall purpose of a change or a batch of changes.  If
  you think that a change calls for explanation, you're probably right.
  Please do explain it--but please put the full explanation in comments
  in the code, where people will see it whenever they see the code.  For
  example, "New function" is enough for the change log when you add a
  function, because there should be a comment before the function
  definition to explain what it does.

I like to encourage explanations in comments rather than in commit logs
(for instance the kernel seems to have long stories in commit logs and
comparatively terse comments.)

I find the named-entity-level description of changes often more readable
that the line-oriented diff—because we manipulate programming language
constructs which are more than mere lines.

There’s also the positive side-effect of writing a change log: it’s for
me an opportunity to review what I’m going to commit.


Having said that, it is clear that newcomers have a hard time getting
used to it.  For simple contributions, it’s often one of the main
difficulties.

Ludo’.