Re: Script to generate ChangeLogs automatically

[Joseph Myers]

On Fri, 30 Nov 2018, Richard Stallman wrote:

> We have already established that "git blame" and "git log -L" fail to
> do this job reliably.

No, we haven't established that.  We've established that the names in 
*diff hunk headers* from "git diff" or "git show" aren't sufficiently 
reliable - which is a completely different matter.

"git blame" and "git log -L" are tools to be used in the appropriate way 
for the particular entity in question - where the developer will vary the 
commands used as appropriate to that case, based on their experience using 
those tools, the code in question and the results of running previous 
instances of those commands with different options.  With a developer 
familiar with the tools they are using and using them appropriately based 
on their experience, they are fully reliable.

If you want to find something in some files and the results of a first 
grep command show your initial search needs some refinement, you'd follow 
up with further such commands guided by the results of the first one.  
Much the same applies when using these git commands as tools to 
investigate the history an an entity - they need to give enough 
information for a human developer to decide whether to run another such 
command, they do not need a single recipe that will always give exactly 
the required information regardless of the peculiarities of the entity in 
question and its history.

Just like other command-line tools, text editors, etc., they are tools 
people learn to use over time through experience using them in different 
situations - they are not tools where you can give a one-off recipe that 
will always meet all someone's requirements, and they are not tools people 
should expect to understand purely through reading documentation, without 
actually using them in practice when they need to look at past changes to 
an entity.

> Fortunately, a good candidate is now being developed.  With some
> attention to the complex cases, we could have a tool that is entirely
> adequate.  Then we could stop writing lists of entity names by hand,
> and not sacrifice anything in future maintenance.

Anything requiring an up-front examination of 17000 source files in glibc 
(or 86000 source files in GCC, etc.), written by hundreds of people over 
three decades, to identify all relevant formatting peculiarities and 
ensure a script handles them - as opposed to handling all the common 
cases, which was the previously stated requirement ("reliably enough that 
errors are rare and not a problem") - is clearly not a practical solution.

-- 
Joseph S. Myers
address@hidden