[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
- Re: Using VC for change descriptions, (continued)
Re: Using VC for change descriptions, Alfred M. Szmidt, 2018/01/02
- Re: Using VC for change descriptions, Joseph Myers, 2018/01/02
- Re: Using VC for change descriptions, Alfred M. Szmidt, 2018/01/02
- Re: Using VC for change descriptions, Joseph Myers, 2018/01/02
- Re: Using VC for change descriptions, Mike Gerwitz, 2018/01/03
- Re: Using VC for change descriptions, Alfred M. Szmidt, 2018/01/03
- Re: Using VC for change descriptions,
Joseph Myers <=
- Re: Using VC for change descriptions, Paul Eggert, 2018/01/03
- Re: Using VC for change descriptions, John Darrington, 2018/01/04
- Re: Using VC for change descriptions, Richard Stallman, 2018/01/08
- Re: Using VC for change descriptions, Paul Eggert, 2018/01/09
- Re: Using VC for change descriptions, Richard Stallman, 2018/01/09
- Re: Using VC for change descriptions, Paul Eggert, 2018/01/10
- How much explanation to include in change descriptions, Richard Stallman, 2018/01/15
- Re: How much explanation to include in change descriptions, Paul Eggert, 2018/01/16
- Re: How much explanation to include in change descriptions, Joseph Myers, 2018/01/16
- Re: How much explanation to include in change descriptions, Richard Stallman, 2018/01/16