On Wed, 3 Jan 2018, Alfred M. Szmidt wrote:
> So maybe for some changes, the mechanical ones, maybe we should extend
> the format of ChangeLog entries to provide an easier way of writing
> them. Maybe just listing the directory, and that would be a kind of
> "all files under this" have been changed in this manner?
>
> * sysdeps/ (__NREG): Renamed from NREG.
The logical nature of that change does not focus on the particular
identifiers, or link cases where the same identifier is incidentally
involved in different files. It's more like:
* sysdeps/**/sys/ucontext.h [!__USE_MISC] (*): Rename to __* where
original name not reserved by POSIX, and update users of the
original identifiers.
Which doesn't name the individual identifiers changed within the files
(but does indicate that the files changed are various sys/ucontext.h
headers).
If you reduce down to that point the ChangeLog entry no longer wastes much
time - but I don't think it actually adds to the main human description in
the commit message, either.
> Here is a simple example of where the ChangeLog is far more clear then
> the diff, the diff says that get-buffer-window-list change, but that
> isn't the case. The form is also bit complicated where it is hard to
Well, if you want to list entities changed even when the funcname line is
within the diff context you could use git diff -U0 within the
entity-listing script. The diffs with -U0 are less useful, but the entity
names would be more accurate.
I think it's expected people will apply common sense when there is a
funcname line within the diff hunk and see immediately what each part of
the diff hunk is changing - the hunk header shows the previous funcname
line as of the top of the diff hunk.
> Or this example, can you at a glance say what changed in the diff?
> Don't you think that the ChangeLog entry far more useful description
> of the change? How would this be presented by diff in a more
> managable manner?
>
> commit 21ecda1045f45ba8468a6d1d4519527a18797f27
> Author: Stefan Monnier <[email protected]>
> Date: Fri Jul 7 16:58:30 2017 -0400
>
> * lisp/window.el (display-buffer--special-action): Use a closure.
You still need a summary description in any case. In cases where a
one-line ChangeLog entry suffices, the commit summary would no doubt be
very similar to what goes in the ChangeLog entry.
It's cases where the ChangeLog entries become long that they diverge from
the human-level description of the change as a whole, and become less and
less useful for understanding the change.
--
Joseph S. Myers
[email protected]
