Re: Using VC for change descriptions

[Joseph Myers]

On Sun, 7 Jan 2018, Richard Stallman wrote:

>   > Here is a simple example of where the ChangeLog is far more clear then
>   > the diff, the diff says that get-buffer-window-list change, but that
>   > isn't the case.
> 
> If the identification of entities changed, given by VCS tools,
> is erroneous, using that instead of listing the entities in the history
> is a non-starter.
> 
> But this is just a bug.  If we fix it, it will become a thing of the
> past.  Joseph, would you like to fix it?

I don't think that example is erroneous.  The hunk header shows the 
previous funcname line before the start of that diff hunk.  If there is a 
funcname line within the diff hunk, it's immediately obvious what is being 
changed.  This is just the same as GNU diff -p.

>   > It's a line beginning with a letter, underscore or $, according to the 
>   > manpage.
> 
> If I understand this, it will cause trouble for C.
> In C, this will cause return-type lines to be taken for entity names.

But only for an interval of a single line (the line with the return type).  
For any change within the function, the previous funcname line will be the 
one with the function name.

> So will strings that are split across lines with \n -- in some cases.

Splitting using string constant concatenation -

  "line 1\n"
  "line 2\n"
  "line 3\n"

rather than

  "line 1\n\
line 2\n\
line 3\n"

avoids that issue.  And since the latter example confuses git diff and 
diff -p, so making writing ChangeLog entries much more painful as diff 
output is the most convenient way of identifying changed entities when 
writing ChangeLog entries, using the former format is naturally more 
convenient already.  (The latter also confuses Emacs if you try to use TAB 
to indent the lines ending with backslash-newline.)

> Smarter code to find and list entities could overcome these problems.

I think we are going ever further into the wrong problem.  My hypothesis 
is that for the vast bulk of changes, a list of changed entities is never 
going to be of use in future development - so in the rare cases where it's 
both relevant and complicated to generate, it can entirely appropriately 
be left to the person who will use the list to generate it by examining 
the diffs.

-- 
Joseph S. Myers
address@hidden