Re: Script to generate ChangeLogs automatically

[Joseph Myers]

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

>    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.
> 
> Your decsription on how to use those two commands is I think good
> reason why they are not suitable.  One does not need to learn yet
> another tool for reading ChangeLog entries.  One does not need to
> learn how multiple version control systems these things in their own
> particular ways.  And one does not need to figure out magical
> incantations to get just the right result.

There are many different cultures in computing with their own assumptions 
regarding the background knowledge people will have and the natural ways 
of configuring, building and distributing software.

We make many assumptions of people building and contributing to GNU 
packages.  We assume they are familiar with use of the command line on 
Unix-like operating systems.  We assume that they know what to do with 
.tar.{gz,xz,...} files.  We assume that following instructions in a text 
file for using configure / make / make install is the natural way to 
install something rather than clicking on an installer.  For contributing, 
people are expected to be familiar with using a text editor to edit files 
in a range of formats and languages, adapting to the code style used in 
those files.

People need to use a range of tools to find their way around a source tree 
with tens of thousands of files and work out which ones are relevant to 
edit to address their issue.  For many things in glibc, people need to be 
familiar with many advanced GNU make features, with properties of the ELF 
object format and symbol aliases, with issues around ABI compatibility and 
symbol versioning, with namespace requirements of different standards, 
with peculiarities of various CPU architectures where those influence 
things in glibc.

For any project, people need to become familiar also with how that project 
uses its mailing lists, its issue tracker, its version control system 
(there are many different branching conventions, for example, and you need 
to know which branches to look at and which contributions should go on), 
and so on.

Just because we are very familiar with many of these things does not mean 
people did not have to learn them - there is a great deal of background 
people have to learn to contribute in various areas to such low-level 
software on a Unix-like operating system.  If someone has prior 
familiarity in a related culture - say, of contributing to the Linux 
kernel, or to FreeBSD - of course there is less they need to learn.  If 
their prior knowledge is of working on web applications in JavaScript, 
they may have more to learn.

I don't think tools for understanding project history should be considered 
any different from all the many other things people need to learn about 
for working on large, complicated, low-level projects.  People start 
learning a subset of those things and gradually learn more of them and 
become more expert in them as they do more work on the project.  That 
describes people becoming familiar with the Unix-like command line; it 
describes people becoming familiar with the source code of a particular 
project; it describes people becoming familiar with git.

In fact, nowadays, for much software development, I think git is pretty 
much as basic a thing people learn as the Unix-like command line - the 
person previously working on web applications in JavaScript is very likely 
to be using git when doing so.  If they have been working on most non-GNU 
free software projects, they have very likely been using git but not 
ChangeLogs.  Even if they don't know git, becoming familiar with git is 
only a tiny part of becoming familiar with all the things that are 
relevant to working fluently on glibc or another large low-level project, 
and people can learn it incrementally just like all the other things.

Code, comments and commit messages all embody similar assumptions about 
the background knowledge people will have; they explain things that need 
explanation in the context of that background knowledge, rather than 
repeating explanations of the great many things that are expected to be 
understood when working on the project.  For a beginner, looking at the 
history of a complicated project will tend to be of limited value; as they 
become more experienced in the project, the history will be of more use to 
them, and at the same time they will become more experienced with the 
tools for looking at it.

We don't expect code in glibc to work with all C compilers or operating 
systems or object file formats or linkers or make implementations.  Just 
as we freely make use of powerful features of GCC, of Linux and Hurd, of 
ELF and GNU linker features, of GNU make, and expect contributors to 
become familiar with those features as needed, so we should not try to 
shoehorn version control information into the lowest common denominator of 
what can readily be described in a single text file.  Expecting 
contributors to use appropriate git features to understand the glibc 
history is just as appropriate as expecting them to learn the GNU make 
features used in the glibc Makefiles rather than insisting that the 
Makefiles must work with POSIX make features only.  This need to learn 
lots of things to get into a project would apply to pretty much *any* 
project with tens of thousands of source files.

If someone changes something in glibc and find the result fails to build 
or fails to pass the glibc testsuite, they then need to debug the problem.  
Debugging a problem like that is much more complicated, and much less 
susceptible to having a single set of instructions to follow, than the 
case of investigating history using git.

-- 
Joseph S. Myers
address@hidden