Re: Using VC for change descriptions

[Alfred M. Szmidt]

   >    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).

Diffs in no way provide the same easy to read, and process information
that a ChangeLog entry does.  For some languages, specially Lisp,
where moving the level of an form will create a totally whacky diff.  

   (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.)

This suggests that we need a better format, not that we should drop
it. 

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.

This would have the disadvantage that you cannot grep for the file in
ChangeLog -- but since you can get the log of a file maybe that would
be ok?

Or introduce regexps? But that comes with its own can of worms.

   > 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.  

You overexagerate the amount of time it takes, it definitly does not
double it, it takes only a few seconds for a small change, and tops
half a minute for a large one like the one you provided as an example.

   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.

I find the ChangeLog entry indispensable.  Both when writing a patch,
but also later in the life of a project.  Diffs in their current form
do not provide the same overview as a ChangeLog entry, maybe it is
possible to somehow extract this but that is not done today.

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
see what got modified.  Where as the ChangeLog entry makes it clear
what we did, and a summary of why (the summaries are a really good
addition, and should be encouraged far more!).

   commit 451823b0e5e71de8949bb0eadc9ea52ec795754f
   Author: Martin Rudalics <address@hidden>
   Date:   Sat Oct 28 11:37:26 2017 +0200
   
       Don't allow (minibuffer-window-active-p nil) to return t
       
       * lisp/window.el (minibuffer-window-active-p): Return t
       only if WINDOW is a live window.
   
   diff --git a/lisp/window.el b/lisp/window.el
   index 5d9409b..f87294c 100644
   --- a/lisp/window.el
   +++ b/lisp/window.el
   @@ -2583,7 +2583,7 @@ get-buffer-window-list
    
    (defun minibuffer-window-active-p (window)
      "Return t if WINDOW is the currently active minibuffer window."
   -  (eq window (active-minibuffer-window)))
   +  (and (window-live-p window) (eq window (active-minibuffer-window))))
    
    (defun count-windows (&optional minibuf)
       "Return the number of live windows on the selected frame.

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 <address@hidden>
   Date:   Fri Jul 7 16:58:30 2017 -0400
   
       * lisp/window.el (display-buffer--special-action): Use a closure.
   
   diff --git a/lisp/window.el b/lisp/window.el
   index 43e9e99..2b979f4 100644
   --- a/lisp/window.el
   +++ b/lisp/window.el
   @@ -7192,9 +7192,9 @@ display-buffer--special-action
           (let ((pars (special-display-p (buffer-name buffer))))
         (when pars
               (list (list #'display-buffer-reuse-window
   -                       `(lambda (buffer _alist)
   -                          (funcall special-display-function
   -                                   buffer ',(if (listp pars) pars)))))))))
   +                       (lambda (buffer _alist)
   +                         (funcall special-display-function
   +                                  buffer (if (listp pars) pars)))))))))
    
    (defun display-buffer-pop-up-frame (buffer alist)
      "Display BUFFER in a new frame.