[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Using VC for change descriptions
From: |
Joseph Myers |
Subject: |
Re: Using VC for change descriptions |
Date: |
Tue, 2 Jan 2018 21:17:51 +0000 |
User-agent: |
Alpine 2.20 (DEB 67 2015-01-07) |
On Tue, 2 Jan 2018, Alfred M. Szmidt wrote:
> 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.
It's a purpose that is substantially covered by the general access to the
diffs themselves through public version control (which was not so
generally available at the time when the ChangeLog format was introduced).
The paragraphs describing the change in free form do say what changed - at
the logical level appropriate to the change in question. When they don't
mention particular named entities changed, that's a feature, not a bug -
by naming the entities most relevant to the point of the change but not
those that are only changed as part of some wider mechanical change, this
means that looking for mentions of a function is more likely to find
changes in which that function is significantly involved, which are more
likely to be of interest than the mechanical ones. (Whereas it's commonly
the case when e.g. looking at changes to some function in GCC that the
vast bulk of the changes are global mechanical changes, with very long
ChangeLog entries but completely irrelevant to whatever I'm looking for
related to the function.)
> 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
A logical description of the change at an appropriate level for that
change is even easier for a human to process than the ChangeLog entry.
If someone is studying the details of the source code and how it changed
at the level of wanting to know how individual bits of the internals
changed in a given revision, then the diffs are much clearer than the
ChangeLog at showing those details of the change. If someone is not
studying the source code and how it changed at that level, the logical
description is much better; reading the logical descriptions of changes
gives a much better understanding of how the software has developed than
reading the ChangeLog entries (and it's always possible to delve into the
diffs for any particular change of interest).
People looking at development of a piece of software already have, in
increasing levels of detail:
1. The NEWS file listing changes at the user level.
2. The documentation included with the software (updated when new features
are added) and the comments (explaining the code as it is as opposed to
the differences from previous versions thereof).
3. The descriptions of each change at the logical level of what changed,
as appropriate to the individual change, naming individual entities only
where appropriate to an understanding of the changeset.
4. The mailing list archives, bug tracker etc. with all the surrounding
development discussions.
5. The version control history showing the exact content of every change.
It's in the context of having all of those available that I claim the net
value of "3.5. Physical descriptions of changes decomposed at the level of
changed named entities, in ChangeLog format." is negative.
> 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).
ChangeLog format effectively doubles the time required to implement
certain kinds of changes - first you have to make the change (some logical
change involving many repetitive edits to many entities), then repeat the
description for each individual edit in a way that's often more verbose
than the diffs themselves. Any benefit from having it is much less than
the benefit from another change fully implemented and written up in the
time otherwise required to write the ChangeLog entry for the first change.
--
Joseph S. Myers
address@hidden
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, 2018/01/02
- Re: Using VC for change descriptions,
Joseph Myers <=
- 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
- How much explanation to include in change descriptions, Richard Stallman, 2018/01/15