Re: Using VC for change descriptions

[Joseph Myers]

On Tue, 2 Jan 2018, Alfred M. Szmidt wrote:

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

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

-- 
Joseph S. Myers
address@hidden