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