Re: Circumstances in which ChangeLog format is no longer useful

[Alfred M. Szmidt]

   >    1. The package has a public version control system.
   > 
   >    (Rationale: this ensures people can see what changed, just as with
   >    ChangeLogs, but can see *exactly* what changed rather than just the
   >    brief descriptions.)
   > 
   > I think that rationale is incorrect, just because you have a public
   > version control system does not mean that you can see what actually
   > changed.  Going through multiple megabytes of diffs is not feasible,
   > and searching for when something was renamed, added, removed, etc is
   > something no tool is capable of providing.

   That's a function of a busy project and is the same whether you look at 
   commit logs, diffs or ChangeLog messages.

That doesn't address how you go through a diff to see when a function
was added/removed/renamed/moved/..., neither diff nor annotate do
those things -- nor can they in the general case.  Think non-C
language, weird configuration files, etc.  And they are still not
available in binary packages or tarball releases.

   >    2. The version control uses a distributed version control system.
   > 
   >    (Rationale: this ensures people can get a complete copy of the
   >    history of what changed, as they can with ChangeLog files in
   >    releases.)
   > 
   > How would the information that is normally available in a ChangeLog
   > file be populated if all that information is in the VCS?  That would
   > still be needed for normal tarballs and the like when VCS is out the
   > window.

   I wouldn't object to shipping the version control history in tarballs, if 
   necessary to stop having to write in the ChangeLog format (or having 
   tarballs with and without the version control history).  

That would ballon the tarball so much that it would be unacceptable,
emacs has a .git directory that is around 1.8G on my machine, glibc
would be 400M with .git and all source files.

   Or straight copies of the version control logs, as long as no-one
   actually has to manually write the list of files, named entities
   within those files and what is changed in each named entity
   (instead just having human-written logs describing what changed at
   the logical level).

Emacs already does most of the gory stuff for adding the mundane
information.

   But I believe that people wanting to look at the history are going
   to check out the repository rather than attempting to get it from
   tarballs.

I can only speak from my own experience, but I always persue the
ChangeLog file first.  Only when a project is badly maintained do I go
for the VCS.

   >    It's normal in glibc, for example, for a change to affect many
   >    separate files and named entities in those files, in ways that are
   >    repetitive but not repetitive enough to use e.g. "All callers
   >    changed", and which the ChangeLog format does not provide a good
   >    fit to or result in useful information about the changes not
   >    available from version control.)
   > 
   > Knowing that all callers have been change is I think useful
   > information, why do you think the opposite?

   The point is that the changes are mechanical, but not in a way that 
   corresponds to "all callers changed", and that listing all the named 
   entities changed and how they changed is error-prone, time-consuming 
   (possibly taking longer than writing the patch itself) and results in a 
   ChangeLog entry that is completely useless for people wanting to 
   understand the change (who will want the description at the logical level, 
   and if they want the exact details for each named entity, will find the 
   version control history more useful).

I am having a hard time taking the "completely useless", "waste of
time" argument seriously when the ChangeLog files (be it in VCS, or a
file) are infact used to do exactly that: to understand how code moves
in a project.  If they where so useless and waste full then most GNU
projects would have abandoned them many many years ago, and yet we
still use them very activley, even in gcc and glibc being just two
examples.

While writing repetative ChangeLogs can be boring, I think your
example illustrates a example of how to not write them not why they
might be seen as unneeded.  Just like writing maintainable code, one
needs to write maintainable ChangeLog entries.  There are tools that
help with this, Emacs being one that makes the job very easy (though
in the case of modifying preprocessor directives and what not it does
lack some intelligence).

This is what I would have done, you have only 8 specific changes
touching multiple files, there is no need to repeat them several times
and one could even reduce this a bit further by merging the file lines
into one.  You can even skip the "Likewise." part completely.

So yes, if you write unreadable ChangeLog entries, then they will be
seen as useless.

2017-06-01  Joseph Myers  <address@hidden>

        [BZ #21457]

        * sysdeps/unix/sysv/linux/powerpc/sys/ucontext.h (NFPREG)
        [__WORDSIZE != 32]: Rename to __NFPREG and define NFPREG to
        __NFPREG if [__USE_MISC].
        * sysdeps/unix/sysv/linux/alpha/sys/ucontext.h (NFPREG): Likewise.
        * sysdeps/unix/sysv/linux/mips/sys/ucontext.h (NFPREG): Likewise.
        * sysdeps/unix/sysv/linux/sh/sys/ucontext.h (NFPREG): Likewise.

        * sysdeps/unix/sysv/linux/x86/sys/ucontext.h (NGREG)
        [!__x86_64__]: Rename to __NGREG and define NGREG to __NGREG if
        [__USE_MISC].
        * sysdeps/arm/sys/ucontext.h (NGREG): Likewise
        * sysdeps/i386/sys/ucontext.h (NGREG): Likewise
        * sysdeps/m68k/sys/ucontext.h (NGREG): Likewise
        * sysdeps/mips/sys/ucontext.h (NGREG): Likewise
        * sysdeps/unix/sysv/linux/alpha/sys/ucontext.h (NGREG): Likewise
        * sysdeps/unix/sysv/linux/m68k/sys/ucontext.h (NGREG): Likewise
        * sysdeps/unix/sysv/linux/mips/sys/ucontext.h (NGREG): Likewise
        * sysdeps/unix/sysv/linux/powerpc/sys/ucontext.h (NGREG): Likewise
        * sysdeps/unix/sysv/linux/s390/sys/ucontext.h (NGREG): Likewise
        * sysdeps/unix/sysv/linux/sh/sys/ucontext.h (NGREG): Likewise

        * 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 (__ctx, __ctxt): Likewise
        * sysdeps/m68k/sys/ucontext.h (__ctx): Likewise
        * sysdeps/mips/sys/ucontext.h (__ctx): Likewise
        * sysdeps/unix/sysv/linux/m68k/sys/ucontext.h (__ctx): Likewise
        * sysdeps/unix/sysv/linux/mips/sys/ucontext.h (__ctx): Likewise
        * sysdeps/unix/sysv/linux/nios2/sys/ucontext.h (__ctx): Likewise
        * sysdeps/unix/sysv/linux/powerpc/sys/ucontext.h (__ctx): Likewise
        * sysdeps/unix/sysv/linux/s390/sys/ucontext.h (__ctx): Likewise
        * sysdeps/unix/sysv/linux/sh/sys/ucontext.h (__ctx): Likewise
        * sysdeps/unix/sysv/linux/x86/sys/ucontext.h (__ctx): Likewise

        * sysdeps/unix/sysv/linux/s390/sys/ucontext.h (__psw_t): Use __ctx
        in defining fields.
        * sysdeps/arm/sys/ucontext.h (mcontext_t): Likewise
        * sysdeps/i386/sys/ucontext.h (fpregset_t, mcontext_t): Likewise.
        * sysdeps/m68k/sys/ucontext.h (mcontext_t): Likewise
        * sysdeps/mips/sys/ucontext.h (mcontext_t, fpregset_t): Likewise
        * sysdeps/unix/sysv/linux/m68k/sys/ucontext.h (fpregset_t, mcontext_t): 
Likewise
        * sysdeps/unix/sysv/linux/mips/sys/ucontext.h (fpregset_t, mcontext_t): 
Likewise
        * sysdeps/unix/sysv/linux/nios2/sys/ucontext.h (mcontext_t): Likewise
        * sysdeps/unix/sysv/linux/powerpc/sys/ucontext.h (fpregset_t) 
[__WORDSIZE == 32]: Likewise
        * sysdeps/unix/sysv/linux/powerpc/sys/ucontext.h (mcontext_t): Likewise
        * sysdeps/unix/sysv/linux/powerpc/sys/ucontext.h (vscr_t, vrregset_t ) 
[__WORDSIZE != 32]: Likewise
        * sysdeps/unix/sysv/linux/s390/sys/ucontext.h (fpreg_t, fpregset_t, 
mcontext_t): Likewise
        * sysdeps/unix/sysv/linux/sh/sys/ucontext.h (mcontext_t): Likewise
        * sysdeps/unix/sysv/linux/x86/sys/ucontext.h (struct _libc_fpreg, 
struct _libc_fpstate, mcontext_t): Likewise

        * 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/alpha/sys/ucontext.h (fpregset_t): Likewise.
        * sysdeps/unix/sysv/linux/sh/sys/ucontext.h (fpregset_t): Likewise.

        * sysdeps/unix/sysv/linux/x86/sys/ucontext.h (gregset_t): Define
        using __NGREG.
        * sysdeps/arm/sys/ucontext.h (gregset_t): Likewise.
        * sysdeps/i386/sys/ucontext.h (gregset_t): Likewise.
        * sysdeps/m68k/sys/ucontext.h (gregset_t): Likewise.
        * sysdeps/mips/sys/ucontext.h (gregset_t): Likewise.
        * sysdeps/unix/sysv/linux/alpha/sys/ucontext.h (gregset_t): Likewise.
        * sysdeps/unix/sysv/linux/m68k/sys/ucontext.h (gregset_t): Likewise.
        * sysdeps/unix/sysv/linux/mips/sys/ucontext.h (gregset_t): Likewise.
        * sysdeps/unix/sysv/linux/powerpc/sys/ucontext.h (gregset_t): Likewise.
        * sysdeps/unix/sysv/linux/s390/sys/ucontext.h (gregset_t): Likewise.
        * sysdeps/unix/sysv/linux/sh/sys/ucontext.h (gregset_t): Likewise.

   You know about the changes much more reliably from the VCS than from 
   ChangeLog entries, given that people may forget to write the ChangeLog 
   entry, or may miss out a file or function's changes from it, or may commit 
   with a ChangeLog from a previous version of the patch that doesn't 
   correspond accurately to the committed patch version (given the make-work 
   nature of writing most ChangeLog entries, and given they are something not 
   generally used outside the GNU project, updating them is often something 
   people don't think of doing - again, watching for badly updated ChangeLog 
   entries in patch review is both necessary at present, and essentially a 
   waste of time).

Writing accurate, and descriptive ChangeLogs is just like writing
accurate documentation, both can be wrong, but so can code.  This
falls onto the maintainer to see that all things are good.  Just using
VCS won't solve that.

   >    This form of description is exactly what's the problem.  In the
   >    presence of ubiquitous distributed version control, writing this
   >    style of description is the equivalent of:
   > 
   >      /* Add 1 to i.  */
   >      i++;
   > 
   >    (that is, just repeating the immediately obvious meaning of the
   >    history that everyone can see, and so effectively serving to hide
   >    what's actually interesting about the history at a human level and
   >    *should* be described).
   > 
   > I don't think the comparison is fair, the point of the ChangeLog files
   > is to be able to undo changes.  The comment above doesn't actually

   The point of the VCS is to be able to undo changes.  ChangeLog files, and 
   the form of change description therein, are in no way a substitute for the 
   VCS, and are essentially obsoleted by it.

The ChangeLog is for human consumption, to understand how the code was
changed, VCS does not solve this, not everything is prettily managed
by git diff that shows you function names of code segments change, or
maybe you are using a non-C language where that might be even harder.
Or you have a very long diff, like in your example which is around 1k,
but the ChangeLog entry for it is only 8 managable entries.

       Fix more namespace issues in sys/ucontext.h (bug 21457).

       Continuing the fixes for namespace issues in sys/ucontext.h, this
       patch moves various symbols into the implementation namespace in the
       absence of __USE_MISC.  As with previous changes, it is nonexhaustive,
       just covering more straightforward cases.

       Structure fields are generally changed to have a prefix __ in the
       absence of __USE_MISC, via a macro __ctx (used without a space before
       the open parenthesis, since the result is a single identifier).
       Various macros such as NGREG also have leading __ added.  No changes
       are made to structure tags (and thus to C++ name mangling), except
       that in the (unused) file sysdeps/i386/sys/ucontext.h, structures
       defined inside other structures as the type for a field have their
       tags removed in the non-__USE_MISC case (those structure tags would
       not in any case have been visible in C++, because in C++ the scope of
       such a tag is limited to the containing structure).  No changes are
       made to the contents of bits/sigcontext.h, or to whether it is
       included.  Because of remaining namespace issues, this patch does not
       yet fix the bug or allow any XFAILs to be removed.

   describes the logical nature of the change (including what is *not* 
   changed, where relevant, which ChangeLog files would never mention), at 
   the appropriate level for people to understand it.  

Why do you think that the ChangeLog can't mention the above?  Or maybe
better yet, since this is a bug fix in a BUGS file or similar.

   > Sifting through multi-megabyte diffs isn't very fun when trying to get
   > a birds eye view of what actually happened in a code base, and this is
   > where ChangeLog entries are super useful and I'd argue totally
   > nessecary for any code base.

   I don't think so.  If someone wants to understand what changed between 
   glibc 2.25 and 2.26 in more detail than the NEWS file gives, they might 
   look at the above sort of description in the commit log; it will be much 
   more helpful to them, and give much more insight into glibc development, 
   than over 10000 lines of ChangeLog entries enumerating files and symbols.  

   If they want to see the files changed, git log --stat.  If they want to 
   see deeper into particular changes, git log -p --stat and look at 
   whichever changes are of interest.

Neither of those are available in tarballs, nor might they be
available in distribution packages where putting up a copy of
ChangeLog can be very useful as well even if you do not have access to
source code.  The NEWS file does not describe code changes, only
user-visible changes, so it is not very useful if you are infact
looking for a problem in a new release.

Cheers, Alfred.