[v2] Script to generate ChangeLog-like output

  The utility of a ChangeLog file has been discussed in various mailing
list threads and GNU Tools Cauldrons in the past years and the general
consensus is that while the file may have been very useful in the past
when revision control did not exist or was not as powerful as it is
today, it's current utility is fast diminishing.  Further, the
ChangeLog format gets in the way of modernisation of processes since
it almost always results in rewriting of a commit, thus preventing use
of any code review tools to automatically manage patches in the glibc
project.

There is consensus in the glibc community that documentation of why a
change was done (i.e. a detailed description in a git commit) is more
useful than what changed (i.e. a ChangeLog entry) since the latter can
be deduced from the patch.  The GNU community would however like to
keep the option of ascertaining what changed through a ChangeLog-like
output and as a compromise, it was proposed that a script be developed
that generates this output.

The script below is the result of these discussions.  This script
takes two git revisions references as input and generates the git log
between those revisions in a form that resembles a ChangeLog.  Its
capabilities and limitations are listed in a comment in the script.
On a high level it is capable of parsing C code and telling what
changed at the top level, but not within constructs such as functions.

For input other than C, the script only identifies if a file has been
added, removed, modified, permissions changed, etc. but cannot
understand the change in content.  The design of the script however is
pluggable, so it should be possible to develop additional parsers to
process other types of files.

I have tested it with a number of commits in the glibc log and also
fixed a couple of errors that were reported earlier.

Transition:

Once this script is in place, it should be possible for us to stop
maintaining the ChangeLog file and rely on the ChangeLog script to
give an output that serves a similar purpose.  Given that the majority
of our code is in C, we have adequate coverage with just the C parser.
In any case the readability of ChangeLog entries for other formats
(makefiles for example) is just too convoluted and is perhaps not even
worth the effort.

I propose that we stop ChangeLog file maintenance once 2.30 opens for
development in February and focus on making the ChangeLog script more
accurate if we encounter bugs.  I will also take another swipe at
patchwork to try and automate things in it now that the ChangeLog is
gone.

If there is agreement, then as part of 2.29 release management I will
update the wiki to reflect the change in our patch submission process
and also mention the Changelog script there for those who need it.  I
believe Joseph is working with RMS to change the wording in the GNU
Coding Standards to make ChangeLog management optional.

Looking forward, once 2.30 is released in August we will be in a good
position to decide if patchwork is useful or if we want to consider
other alternative patch review processes and tools.

ChangeLog:

	* scripts/gen-changed-entities.py: New script.
---

Changes from v1:

- Rewrote the macro nesting detection logic.
- Changed the way macro hacks are detected, now I build a list of macro
  definitions in addition to reading libc-symbols.h for symbol hack
  definitions.  This in combination with manual substitutions for known
  bad macros seems sufficient for accurate parsing.
- Fixed multiple issues reported by Richard and Alfred.

 scripts/gen-changed-entities.py | 1099 +++++++++++++++++++++++++++++++
 1 file changed, 1099 insertions(+)
 create mode 100755 scripts/gen-changed-entities.py

[v2] Script to generate ChangeLog-like output

Commit Message

Comments

Patch