Re: Script to generate ChangeLogs automatically

[Joseph Myers]

On Fri, 30 Nov 2018, Alfred M. Szmidt wrote:

>    I think it's a feature for git blame not to show changes when a function 
>    was moved without its contents being changed, not a bug.
> 
> I certainly do not, it can mean the difference between working code
> and non-working code, and it can change the semantics.  Only in C, it
> would be the difference between a function getting a proper prototype,
> or not having one and defaulting to returning int.  And if you have
> -Werror .. errors or not.  It has lead me on several not so fun goose
> chases.

Well, whether the function *was* moved (versus other functions moving 
around it) is inherently a subjective question.  There's no guarantee that 
the reader would agree with the commit author's interpretation of which 
functions were moved, or that either interpretation is actually the 
relevant one for causing any bugs.

>    It is considered good practice that a commit rearranging code
>    should not at the same time make changes to that code, precisely
>    because of the difficulty in seeing what those changes are when
>    mixed up with a rearrangement, and if you follow that practice,
>    repeating the "git blame" (or "git log -L", etc.) command with a
>    series of different revisions named should work well.
> 
> I don't think we can assume this with code that is over 10, 20 or 30
> year old.  glibc has changed between three version control systems,

All the conventions, and stopping writing ChangeLog format, are supposed 
to be for *future* commits - not involving removal of any *past* ChangeLog 
entries where the history may be messier.

> Emacs has gone through at least 5, just like GCC.  In 10 years,
> something new will probobly exist...  Trusting one command that is so
> prone to change with the colour of the season seems to be a mistake.

I think we can assume that if a package converts to a new version control 
system, it will be even more powerful than the one in current use and even 
better at the things people do with version control, including the various 
ways of examining history.  As I said in 
<https://lists.gnu.org/archive/html/bug-standards/2017-07/msg00002.html>, 
"you could add a requirement not to switch away from a distributed VCS or 
to switch to a different VCS without converting history".  (But really we 
should trust maintainers to apply common sense in such matters; that 
shouldn't need to be stated.)

> ChangeLog entries have endured almost 40 years.  Why not keep them?

Because they were designed for a world where people didn't have immediate 
local access to the complete history and where a typical change was very 
different from the very many changes we see now in glibc or GCC where an 
enumeration of changed entities is poorly matched to the appropriate level 
of description for understanding the change.

A good comment describes things that aren't obvious from the code it 
comments on; it doesn't duplicate the code, because people are looking at 
it in conjunction with that code.  A good commit message is a comment on 
the commit and should describe things that aren't obvious from the commit, 
but not the low-level details of what changed in each entity (because 
anyone having the commit message can nowadays be assumed to have it 
together with the diffs of the commit itself).  ChangeLog entries are 
defined to contain more or less exactly the content that is least useful 
because it is most duplicative of the diffs of the commit.

>    We could have such a policy - about making commits in a form that
>    facilitates use of tools to examine the changes to particular
>    entities - as something needed if not maintaining ChangeLog-format
>    logs.  (When I started this discussion in
>    <https://lists.gnu.org/archive/html/bug-standards/2017-07/msg00000.html>
>    I listed five conditions that seemed appropriate for not using
>    ChangeLog format; this would be a sixth, although I don't think
>    Paul Eggert's proposed patch to the standards necessarily
>    incorporated all the proposed conditions.)
> 
> But isn't this exactly what ChangeLog entries (not to be confused with
> the file) provides?

The point is to provide the useful functionality they provide without the 
make-work of writing descriptions of every change at that fixed level that 
closely duplicates the change itself, in addition to describing the change 
itself at the logical level appropriate for the change, and in addition to 
actually making the change itself.  The conditions are intended to be 
conditions sufficient for ChangeLog entries not to be useful.

-- 
Joseph S. Myers
address@hidden