Re: Circumstances in which ChangeLog format is no longer useful

[Rical Jasan]

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:

>         * sysdeps/unix/sysv/linux/x86/sys/ucontext.h (NGREG)
>         [!__x86_64__]: Rename to __NGREG and define NGREG to __NGREG if
>         [__USE_MISC].
>         ...
> 
>         * sysdeps/unix/sysv/linux/powerpc/sys/ucontext.h (NVRREG)
>         [__WORDSIZE != 32]: Rename to __NVRREG and define NVRREG to
>         __NVRREG if [__USE_MISC].
>         ...
> 
>         * sysdeps/arm/sys/ucontext.h (__ctx): New macro.
>         ...
> 
>         * sysdeps/i386/sys/ucontext.h (fpregset_t, mcontext_t): Use __ctxt in 
> defining fields.
>         ...
> 
>         * sysdeps/unix/sysv/linux/powerpc/sys/ucontext.h (fpregset_t) 
> [__WORDSIZE != 32]: Define using __NFPREG.
>        ...
> 
>         * sysdeps/unix/sysv/linux/x86/sys/ucontext.h (gregset_t): Define 
> using __NGREG.
>         ...

as well as any all other commits whose messages contained NFPREG.  To be
more thorough:

$ git log -E --grep='N(FP|G|VR)?REG'

Most of my experience with the dually-maintained commit messages and
ChangeLogs has been with glibc, and everything in the ChangeLog is
already in the commit message, so there's nothing additionally useful,
and the ChangeLog itself doesn't serve as a means to actually find
/what/ changed either.  For that, just add `-p':

$ git log --grep=NFPREF -p

and you get the commit message, which explains why the change was made,
all the files that were touched and a brief synopsis of what changed in
them (duplicated in the ChangeLog), and then the entire diff.

(Note that you also get the diff of the ChangeLog in the patch, which
has always been somewhat amusing. :)

When working on patches to glibc, I ignore the ChangeLog until I
actually push, then I just amend the commit at the last second after
copy/pasting only the portion of the commit message that goes in the
ChangeLog.

Point being, there is no additional information in the ChangeLog that is
not already in the commit, at least in the relevant projects I've been a
part of, given their standards for commit messages.

As another example, say I wanted to search for all changes to a
particular file.  Since the commit message contains the same content as
the ChangeLog entry:

$ git log --grep=sysdeps/arm/sys/ucontext.h [-p]

Using git (I know the conversation is more generically about VCS, but
this just happens to be the one I'm familiar with), it's also possible
to search for changes within the patch itself.  The ChangeLog entry
can't even refer you to the code that changed in the first place, so
it's effectively a dead end for that use-case.

Say you're interested in changes to the fpregs member of the mcontext_t
struct.  Assuming the diff below is associated with the ChangeLog entry
above, the closest that I see you could get would be searching the
ChangeLog for mcontext_t.  Personally, what I would be doing instead is:

$ git log -G'fpregs' -p

which would catch this:

> Than going over the following:
> 
> diff --git sysdeps/arm/sys/ucontext.h sysdeps/arm/sys/ucontext.h
> index 37277f0..722300a 100644
> --- sysdeps/arm/sys/ucontext.h
> +++ sysdeps/arm/sys/ucontext.h
...
> @@ -82,10 +91,12 @@ typedef struct fpregset
>  /* Context to describe whole processor state.  */
>  typedef struct
>    {
> -    gregset_t gregs;
> -    fpregset_t fpregs;
> +    gregset_t __ctx(gregs);
> +    fpregset_t __ctx(fpregs);
>    } mcontext_t;

and also provide the commit message, which has exactly the same
information as the ChangeLog, plus a detailed description of the change,
and the whole patch for examination.  (All this, of course, along with
the same set of information for every other commit that touched fpregs
in some way.)

Nowhere in any of this forensic workflow would the ChangeLog be useful
to me, and in the development workflow, it's only an additional
step---remembering to copy/paste redundant information.


Now, the ChangeLog has proven useful for finding leads when
investigating very old changes, but its utility is still limited because
it can't actually take me to the code changes themselves.  Occasionally,
however, I can confirm that something was in fact added ca. 1998, for
example.


So, I am in favour of allowing projects to rely solely on VCS, where
their commit standards at least provide the intended information and
functionality of the ChangeLog (and possibly, as I hope to have shown
using examples from my own workflow, much, much more), and not have to
maintain the ChangeLog in addition, moving forward.

I understand there may be concern about the ChangeLogs ceasing to record
changes because they are packaged with the release.  Speaking only from
personal experience, when I want to know about changes made between
versions -- to make sure nothing jumps out at me as a potential issue
with a given system, or to see if a particular bug I've been bit by has
been addressed, for example -- I look first for a NEWS file (after
reading the README, of course ;), then maybe VERSION, WHATS_NEW,
RELEASE-NOTES, etc.  Something that summarizes significant changes
between releases.

If I want to know a project's entire history, chnage-by-change, then I
just go checkout the project's website and find their public repo (or
maybe it was in the README, or HACKING) and use their VCS.  I wouldn't
go to the ChangeLogs from a release tarball expecting to feel current
with active development or like I had the resources to truly dig in,
even if I were just looking for information on a particular change.
That's exactly what their VCS is for.  A quick grep of the ChangeLog
isn't out of the question, but is less likely in my experience to really
get me what I'm looking for (plus, if I'm at the point where I'm
interested in digging through a project's changes, I'm probably looking
to fix something or hack a bit, and I'm going to want to clone their
repo anyway and adapt to their workflow for patch submission).


Others may have very different habits, procedures, etc., but I wanted to
weigh in with mine, to hopefully provide some insight on at least
somebody's workflow/tendencies.  I have no idea how representative I may
or may not be, so hopefully others weigh in too, especially if they can
demonstrate how the ChangeLog is more or just as useful to them as using
a project's VCS.


Thank you,
Rical