Re: Circumstances in which ChangeLog format is no longer useful

[Rical Jasan]

On 07/31/2017 06:03 AM, Joseph Myers wrote:
> On Sat, 29 Jul 2017, Rical Jasan wrote:
> 
>> On 07/29/2017 03:21 AM, Alfred M. Szmidt wrote:
>>> It is clearly more useful to read the following to grasp what
>>> happened,
>>>
>>>         * sysdeps/unix/sysv/linux/powerpc/sys/ucontext.h (NFPREG)
>>>         [__WORDSIZE != 32]: Rename to __NFPREG and define NFPREG to
>>>         __NFPREG if [__USE_MISC].
>>>         ...
>>
>> $ git log --grep=NFPREG
>>
>> would be what I would do and would reveal all of the following:
> 
> My proposal would mean the git logs would not include ChangeLog-format

$ git log --follow file

will show all commits that affected FILE, also accounting for renames,
but...

> logs (as the problem is with needing to write in that format, for projects 
> for which it is not well-suited, rather than with putting that format in 
> ChangeLog files once written), and so, in this case, would not name the 
> NFPREG identifier at all in the log message, only in the diff itself.  
> (Of course, some logs would name the changed entities - where that's a 
> relevant level for describing the change in question, which it isn't here.  
> So the logs naming a function would in fact be those most likely to be 
> relevant to understanding the history of that function, excluding those 
> where it's incidental to a larger change.)

My only issue with not enumerating affected functions is increased
difficulty in tracking changes to them.  Git (unsure as of which
version) does have:

$ git log -L :<funcname>:<file>

syntax, but I haven't used it enough in practice to know how reliable it
is.  Neither do I know how that translates to tracking variables,
macros, structs, or other data types of interest, if at all.

I apologize for misunderstanding the intent of the proposal.  While I
don't use ChangeLogs, I actually use that format in my personal projects
(which I'll blame glibc habituation for :), as I do find it a simple and
reliable form of annotation within the commit message (and thus with
`git log --grep=').  While it isn't useful to me in a ChangeLog, I find
it so in commit logs.

Further, when you stated in [1], regarding the ChangeLog format,
"without providing any corresponding benefit", I often find myself
performing more thorough review of the final patch for submission,
ensuring I've documented (no matter how tersely; e.g., "New function")
everything that I've touched, which I find helpful as a means of
providing quality documentation of my changes.

Do you know of a good way to cull changes to, for example, a struct,
where the diff would only show changes to its members?  IOW, an
alternative to:

            (mcontext_t): Use __ctx in defining fields.

For the example patch being discussed, the only reason it would show up
with `git log -G mcontext_t' is because of the ChangeLog entry---there
are otherwise no lines in the diff where an added or removed line
contains mcontext_t.  The only reason it shows up with `git log
--grep=mcontext_t' is again because of the ChangeLog format segment of
the commit message---it is not contained within the textual description.

So, I have to say at this point that I see value in the ChangeLog
format, just not the ChangeLogs themselves.

Rical

[1] https://lists.gnu.org/archive/html/bug-standards/2017-07/msg00000.html