Re: Using VC for change descriptions

[Joseph Myers]

On Sun, 26 Nov 2017, Paul Eggert wrote:

> Richard Stallman wrote:
> 
> > there are git commands for asking which functions were
> > affected by a certain commit, and finding commits that affect a
> > certain function....  Are
> > there unusual cases they don't handle right?  For instance, do they
> > work for macro definitions in C?
> 
> 'git blame' and 'git diff' are line-oriented, and work equally well for macros
> vs functions vs other kinds of definitions. They're the commands I normally
> use (perhaps via front ends). I'm not sure which git commands you're referring
> to as being function-oriented.

It's "git log -L :<funcname>:<file>".  (But I very rarely use that, 
generally finding blame/annotate more useful.)

If there are particular cases where a developer wants the "git log -L" 
functionality but finds the default funcname regular expression 
unsuitable, and blame/annotate aren't sufficient, they can either use the 
other form of "git log -L" where arbitrary regular expressions specify the 
start and end of the region to generate logs for, or add appropriate 
configuration to .gitattributes and .git/config.

> Many GNU developers have already been doing that for years. For example, when
> developing I do not look at ChangeLog files in the GNU projects I help
> maintain, except for ancient history that predates use of Git or Bzr or CVS.
> So this experiment has already been done.

Indeed.  We know that in practice distributed VCS history is a suitable 
substitute for ChangeLog files, including (from experience with non-GNU 
projects) when that history is not in ChangeLog format.

It is also clear in practice that there are certain kinds of changes for 
which the ChangeLog format is poorly suited, because those changes cannot 
readily be described or understood in terms of separate descriptions of 
what they do to each individual named entity affected, or because 
describing in those terms results in a very long description that is 
excessively duplicative of the diffs themselves (which can be seen in the 
VCS history).  In such a case, a good, higher-level description of the 
changes is needed - but adding the ChangeLog-format descriptions of each 
fragment of the changes is extra work that does not provide any 
corresponding benefit.  This is why I think we should stop requiring use 
of ChangeLog format.  (The standards already allow automatic ChangeLog 
file generation from version control history; the issue is with the 
format.)

-- 
Joseph S. Myers
address@hidden