[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Using VC for change descriptions
From: |
Alfred M. Szmidt |
Subject: |
Re: Using VC for change descriptions |
Date: |
Tue, 02 Jan 2018 12:45:05 -0500 |
> 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).
- Re: Using VC for change descriptions, (continued)
- Re: Using VC for change descriptions, Paul Eggert, 2018/01/07
- Re: Using VC for change descriptions, Richard Stallman, 2018/01/15
- Re: Using VC for change descriptions, Paul Eggert, 2018/01/15
- Re: Using VC for change descriptions, Richard Stallman, 2018/01/28
- Re: Using VC for change descriptions, Paul Eggert, 2018/01/28
- Re: Using VC for change descriptions, Joseph Myers, 2018/01/09
- Re: Using VC for change descriptions, Richard Stallman, 2018/01/15
- Re: Using VC for change descriptions, Joseph Myers, 2018/01/16
Re: Using VC for change descriptions, Alfred M. Szmidt, 2018/01/02
- Re: Using VC for change descriptions, Joseph Myers, 2018/01/02
- Re: Using VC for change descriptions,
Alfred M. Szmidt <=
- Re: Using VC for change descriptions, Joseph Myers, 2018/01/02
- Re: Using VC for change descriptions, Mike Gerwitz, 2018/01/03
- Re: Using VC for change descriptions, Alfred M. Szmidt, 2018/01/03
- Re: Using VC for change descriptions, Joseph Myers, 2018/01/03
- Re: Using VC for change descriptions, Paul Eggert, 2018/01/03
- Re: Using VC for change descriptions, John Darrington, 2018/01/04
- Re: Using VC for change descriptions, Richard Stallman, 2018/01/08
- Re: Using VC for change descriptions, Paul Eggert, 2018/01/09
- Re: Using VC for change descriptions, Richard Stallman, 2018/01/09
- Re: Using VC for change descriptions, Paul Eggert, 2018/01/10