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 [email protected]
