ChangeLog's: do we have to?

[Joseph Myers]

As far as I am concerned, the problem with ChangeLogs is one with the 
format rather than one with having files called ChangeLog.  (The GNU 
Coding Standards have permitted automatic generation of ChangeLog at 
release time from version control information since 1996.)

The main issues I see with the format are:

(a) It's a format designed for pre-VCS days and thus involves writing 
descriptions that duplicate what's plain from reading the change itself, 
rather than descriptions that are written on the basis that readers have 
access to the change itself and so the description can better concentrate 
on a higher-level overview of the changes and information that isn't 
obvious simply from reading them.

(b) It forces all descriptions to be at the level of describing what 
changed in each individual named entity in the source code, whether or not 
that is the most helpful level for understanding that particular change 
(and whether or not entity names either exist or are convenient for the 
ChangeLog - a convention designed for C function names works less well for 
C++).

I think that for many projects these outweigh the benefits from forcing 
someone to read through all their changes carefully to write the ChangeLog 
entry.

In the discussions on bug-standards, RMS was amenable to removing the 
requirement for ChangeLog format and the per-entity descriptions of what 
changed - *if* a sufficiently good tool is provided to produce a list of 
the names of the entities changed by a commit.  I don't see such a tool as 
being useful - I think the cases where people might use such lists can all 
be adequately addressed using existing git facilities to e.g. search for 
changes to an entity rather than list entities involved in a change.  But 
I haven't managed to persuade RMS of that.

So, if someone write the entity-listing tool, we should be able to get the 
GNU Coding Standards requirement for ChangeLog format removed (whether or 
not it's still necessary to generate some kind of log of changes at 
release time and put it in a file called ChangeLog).  The tool should be 
able to handle, at least, the main cases where diff hunk headers get the 
name of the changed entity wrong (when the relevant funcname line is 
inside the hunk rather than before it, when the changed entity is a 
#define, at least).

https://lists.gnu.org/archive/html/bug-standards/2018-05/msg00011.html

If the requirement is removed from the GNU Coding Standards, individual 
GNU packages can then make their own decisions about whether to keep using 
ChangeLog format or not.

-- 
Joseph S. Myers
joseph@codesourcery.com