Re: [PATCH] Add a new VCSToChangeLog script

[Siddhesh Poyarekar <siddhesh@sourceware.org>]

On 28/01/19 12:08 AM, Bruno Haible wrote:

> Hi Siddhesh,
>
>> Build a more general script that parses changes in a VCS and then
>> prints it in a ChangeLog format.
> Can you please give some more context?


Sorry about that, there was a pretty extensive conversation on other
lists[1][2][3] and in my hurry to get this out before the glibc 2.29
release I overlooked the fact that everyone on this list may not have
that context.  I've described the intent in response to your questions
below.


>   * Is it a tool meant to operate on the history and produce a (large)
>     ChangeLog file, like gitlog-to-changelog?
>     Or is it a tool meant to help the developer prepare a git commit
>     message and ChangeLog entry, like 'vc-dwim' from Jim Meyering?


The general consensus from those discussions above was that it would be
acceptable to have ChangeLog entries auto-generated to approximate a
ChangeLog entry from the git history, but not just its commit log like
gitlog-to-changelog does but by parsing the contents of the difference
to determine what changed and prepare a ChangeLog entry based on that. 
The result is this script, which is unlike gitlog-to-changelog.  For
projects that need a precise ChangeLog (in the glibc project we have
general agreement on having decent approximations) they can continue
using the gitlog-to-changelog script until vcs-to-changelog.py gets to
the point of being acceptable for them.

I wasn't aware of vc-dwim (or more specifically, vc-chlog) and from the
description it looks like there is overlap.  I'll study that project;
maybe all my work is unnecessary and we can just use vc-chlog...


>   * In the first case, why is it useful for the program to understand
>     the syntax of specific files? Can you show an example? And how
>     would you combine the machine-generated parts with the human-written
>     parts? I mean, an entry without human-written parts, like
>       * foo.c (func1, func2, func3): Modified.
>       * bar.c (func4, func5, func6): Modified.
>     is not particularly useful to look at.

The output is not intended to be human-edited.  The point of the script
is to not have to write or maintain ChangeLog entries at all.  If one
needs to see a ChangeLog-like output (i.e. what changed as opposed to
why and doesn't want to grok the diff), they can use the script with the
relevant refs and get the output.  That's why it is useful for the
script to understand the syntax of specific files.  The script currently
does not look inside functions or structs because it was initially
agreed that only high level changes need to be listed (hence the
'approximation' of a ChangeLog).  The parser can be enhanced to look
further inside in future, and it's on my list to do.  The list is quite
long, so if gnulib or glibc participates in GSoC I'll be happy to mentor
students who express interest in doing this too.


> If the goal is that the tool operates with several version control
> systems, do you also have an adapter 'vcs_svn.py'?

I wrote this for glibc to begin with, but during discussions it was
apparent that other projects would be interested in this as well, which
is why I split out the repo backend to make it easier to add other VCS
backends.  I don't intend to write a vcs_svn.py but if a project is
interested in it, it should be pretty straightforward to write one and
plug it in.  Or they could convince me to write one, but that will be
queued up behind glibc support bits such as the Versions file parser. 
Again, <insert GSoC pitch here>.


> Also, since this is a significant contribution, do you already have
> started copyright assignments to the FSF for your Gnulib contributions?


I should be covered under Linaro's assignment.


>> +    codecs = ['utf8', 'latin1', 'cp1252']
> 1. Can you please use the standardized name 'utf-8'? Use of nonstandardized
>    charset identifiers causes interoperability problems.

I believe that's defined by python, but I'll test if 'utf-8' works and
use that instead.


> 2. Since latin1 is a subset of cp1252, you can omit 'latin1' here.

OK, I'll change this.


Siddhesh

[1] https://lists.gnu.org/archive/html/bug-standards/2018-05/msg00010.html

[2] https://lists.gnu.org/archive/html/bug-standards/2018-11/msg00000.html

[3] https://sourceware.org/ml/libc-alpha/2018-12/msg00855.html