Re: Using VC for change descriptions

[Joseph Myers]

On Tue, 2 Jan 2018, Richard Stallman wrote:

>   > The default regex for identifying funcname lines is good for a range of 
>   > different types of entities and source languages.
> 
> Perhaps I misread the text from the man page when I read it before.
> What is the default regexp, and how is it used?

It's a line beginning with a letter, underscore or $, according to the 
manpage.  I don't think exactly what the implementation looks like inside 
git itself is important.

>   > If you use e.g. "git show" or "git diff" to look at the diffs for a given 
>   > commit, the diff hunk headers show function names (with the same logic as 
>   > git log -L for identifying the relevant function).
> 
> That may help things.  I presume a script can extract the entity
> names from the hunk headers and eliminate duplicates.
> 
> So the remaining question is, is the detection of entities complete,
> or can we make it complete?

Also: is there any need to make it complete?

Part of my argument is that we should trust the developers of each GNU 
package to decide what is useful to include in the logs for that package.  
If they think that in a particular case listing the named entities 
affected by a given change is unimportant and that change is better 
understood at a different level, what basis do we have for thinking we 
know better what is relevant information for understanding the development 
of that package?

"Listing entities changed in developing a GNU package" should be a means 
to an end, not an end in itself.  Conventions for logging changes should 
be aimed at the actual underlying goals (such as enabling someone to find 
which change broke something, which is covered by bisection, git blame, 
etc.), not at particular details that happen to fall out of a particular 
ChangeLog format.

Also: entity names are very unhelpful in some cases.  Consider the 
following fragments from a ChangeLog entry for changes to glibc's 
math/Makefile:

        ($(addprefix $(objpfx), $(libm-tests.o))): Move target and update
        dependencies.
        ($(foreach t,$(libm-tests-normal),$(objpfx)$(t).c)): New rule.
        ($(foreach t,$(libm-tests-finite),$(objpfx)$(t).c)): Likewise.
        ($(foreach t,$(libm-tests-inline),$(objpfx)$(t).c)): Likewise.
        ($(foreach t,$(libm-tests-vector),$(objpfx)$(t).c)): Likewise.
        ($(foreach t,$(types),$(objpfx)libm-test-support-$(t).c)):
        Likewise.
        (dependencies on libm-test-support-*.o): Remove.
        ($(foreach f,$(libm-test-funcs-all),$(objpfx)$(o)-$(f).o)): New
        rules using iterators.
        ($(addprefix $(objpfx),$(call libm-tests-for-type,$(o)))):
        Likewise.
        ($(objpfx)libm-test-support-$(o).o): Likewise.
        ($(addprefix $(objpfx),$(filter-out $(tests-static)
        $(libm-vec-tests),$(tests)))): Filter out $(libm-tests-vector)
        instead.
        ($(addprefix $(objpfx), $(libm-vec-tests))): Use iterator to
        define rule instead.

$(addprefix $(objpfx),$(filter-out $(tests-static) $(libm-vec-tests),$(tests)))
is the name of an entity - in the name of which $(libm-vec-tests) is 
changed to $(libm-tests-vector).  That is, it's what appears on the left 
hand side of ':' in a makefile rule (with some backslash-newlines in the 
middle to reduce line length).  It's true that regular expressions would 
find it hard to extract such a multi-line entity name automatically.  But 
it's also true that naming such an entity in the ChangeLog / commit 
message is useless - that long name with lots of use of GNU make features 
is not something anyone would reasonably search for.

There are four paragraphs of human-level explanation of that change as a 
whole in the commit message (glibc commit 
92061bb033f093cca76e31745cac14c43a1fb29b, "Run libm tests separately for 
each function.").  I don't think the 370-line ChangeLog entry adds 
anything useful - complicated diffs of complicated changes to complicated 
code making heavy use of GNU make features aren't especially readable, but 
the list of what changed in each fragment of the makefile code doesn't 
help in understanding the code and the changes.

>              > o   cpp suitable for source code in the C and C++ languages.
> 
> Is there one for Emacs Lisp?
> 
> Is there one for Bison input?

Those aren't mentioned in the gitattributes manpage.  That doesn't stop 
people writing them, either for a given project or to contribute to git 
itself.  And for Bison input, a typical syntax production would start with 
a line "syntax_production_name:", with subsequent lines in that production 
being indented - so would be covered by the default rule anyway.

-- 
Joseph S. Myers
address@hidden