Using the vcs_to_changelog.py script

[Simon Marchi]

On 2020-02-13 10:42 a.m., Eli Zaretskii wrote:
>> Cc: binutils@sourceware.org, gdb-patches@sourceware.org
>> From: Simon Marchi <simon.marchi@polymtl.ca>
>> Date: Thu, 13 Feb 2020 09:19:28 -0500
>>
>>>  . Some files in our tree are neither C++ nor C: there are Python
>>>    files, Guile files, shell scripts, and Texinfo files, to mention
>>>    just a few: what to do about them?
>>
>> I presume glibc is in the same situation... The script just says that
>> the file is modified.
> 
> So for those other languages, the author of the changeset will have to
> write the entries by hand?  Or are tyou suggesting omitting them
> altogether and staying with file names alone?  (The latter would be
> somewhat boring for the GDB manual, since almost all of it is in a
> single file...)

I am not a user of ChangeLog files myself (other than writing entries for
them), so I would be fine if the entry only mentioned the file name.  But
perhaps others will not, I can't tell.

I don't think it would be practical if some entries were written by hand
and others were generated.  First, I think it would make the contribution
process confusing, but also I don't know how it would work process-wise.

>> If we wanted to get more details for them, we would have to
>> implement new parsers to figure out what changed between two
>> revisions.
> 
> Is that practical?

I presume that it's much harder to make an ad-hoc parser for C and for a
texinfo file.  So if it has been done for C, it should be do-able to texinfo.

>> So the only difference is that we would not provide a manual ChangeLog entry.
> 
> And replace that part with nothing?  I thought something will have to
> be done instead, to have the log messages be as informative as they
> are now.

My understanding from:

  - past dicussions (the big one on bug-
  - the proposed change to standards.texi that you sent

is that the ChangeLog entry is redundant enough with the combination of:

  - a good commit message that explains why the change is done
  - the diff of the change

which are both kept by the VCS.  And for that reason, it's fine not to keep
a ChangeLog file in the VCS.  However, for the benefit of people just using
tarballs, and not the VCS, we generate a ChangeLog file from the diff.
Naturally, the generated ChangeLog will be less informative than one written
by humans (it won't say what changed in a function, it will just say that
the function has been modified), but since that procedure was adopted by glibc,
and is mentioned in the proposed standards.texi change, then it must have been
considered an acceptable compromise.

Simon