Re: Using VC for change descriptions

[Alfred M. Szmidt]

   >    I gave an example in
   >    <https://lists.gnu.org/archive/html/bug-standards/2017-07/msg00002.html>
   >    (bug-standards, Fri, 28 Jul 2017 23:47:19 +0000), both of a
   >    ChangeLog entry and of the corresponding logical description
   >    (summary line plus two descriptive paragraphs) that actually
   >    explains what changed at a more human-comprehensible level.
   > 
   > The example ChangeLog is not a good example, since that is how
   > you are supposed to write them.  I showed you a much shorter, and
   > much more legible version of the same in a follow-up email.

   And I explained in a followup that your version was not actually an
   improvement as it put the focus on incidental use of identifiers
   with the same name in different files, which just takes things
   further away from an understanding of the actual nature of the
   change (make a particular logical set of cleanups in multiple
   files, where the identifiers involved are incidental to the change
   rather than of its essence).

But that is the purpose of a ChangeLog entry, no? To see _what_
changed in a source file.  Not the actual reason for the change.

   > You "summary description" while useful and could/should be
   > included as part of the ChangeLog entry (or commit message), does
   > not tell the reader _what_ changed _where_.

   The diffs tell the reader what changed where.  The summary
   description is written on the basis that people can look at the
   diffs if they want and so developers should write text that
   complements the diffs rather than spending any time duplicating the
   information in them.

A ChangeLog entry is far easier to process by a human, than a large
diff.  For some languages the diffs become really ugly, specially for
example Lisp.  There is no reason why we cannot have the ChangeLog
entry, plus a summary of the actual reason for the change (this is
already suggested AFAIK in the GNU Coding Standards).