bug-standards
[Top][All Lists]
Advanced

[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: Wed, 3 Jan 2018 13:35:51 +0000
User-agent: Alpine 2.20 (DEB 67 2015-01-07)

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 <address@hidden>
>    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
address@hidden



reply via email to

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