[Top][All Lists]

[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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]