Re: Script to generate ChangeLogs automatically

[Joseph Myers]

On Wed, 21 Nov 2018, Per Bothner wrote:

> text from commit-messages.  A list of functions that were removed,
> added, or modified has limited use - what does it get you that
> 'git diff' doesn't?  It's slightly more convenient, that's all.

I'd be fine without having a way to generate that list, but it's a stated 
requirement in 
<https://lists.gnu.org/archive/html/bug-standards/2018-05/msg00003.html> 
and 
<https://lists.gnu.org/archive/html/bug-standards/2018-05/msg00011.html> 
to be able to "generate, from the repo, the list of entities changed -- 
reliably enough that errors are rare and not a problem.".

> One approach is a convention to write commit messages in ChangeLog style:
> A one-line summary, followed by a blank line, followed by more detailed
> changes.  The latter would use ChangeLog conventions/recommendations, except
> without the indentation.  I.e. asterisks in column 1.

The goal is to be able to write messages that just describe the change at 
a higher level rather than repeating the details of the individual parts 
of the change, at the fixed level of what changed in each named entity, 
which can be obtained from the diff itself if desired - essentially, the 
summary line would be the Subject: line of a mailing list message 
proposing the patch, while the rest of the message would be the 
descriptive text that goes in that message to explain and justify the 
change.  (The paragraphs of higher-level description might or might not 
discuss changes to individual named entities, depending on what's 
important for understanding the change.)

Existing rules on what goes in comments would remain unchanged (in some 
cases it can be useful for similar pieces of text to appear in both the 
commit message, for people reading the commit, and in comments in the 
code, for people reading that code in future).

-- 
Joseph S. Myers
address@hidden