Re: Circumstances in which ChangeLog format is no longer useful

[Joseph Myers]

On Sun, 6 Aug 2017, Alfred M. Szmidt wrote:

>    > ChangeLog entries are trivial and quick to write, and save so much
> 
>    This whole proposal is because they are not at all trivial or quick to 
>    write for the sorts of changes that are common in projects such as glibc 
>    or GCC, which are very different from the small local changes illustrated 
>    in the example ChangeLog entries in the GNU Coding Standards.  
> 
> Then we should look into ways to make them quicker for these cases
> instead of throwing out the baby with the bath water.  I showed an
> example on how they are easy and quick to write for changes that
> affect many similar files, still using the current way of writing
> them.  If you can show how they are complicated maybe this dicussion
> can be turned into something a bit more interesting?

I don't think your example was an improvement, either in usefulness of the 
content or ease of writing it.  I think that just about any patch to GCC 
or glibc whose ChangeLog entry is over 10 lines is a case where, given a 
good changeset-level description of the patch (which may or may not refer 
to individual files and functions, depending on what is helpful in that 
context - but in any case, should be written on the basis that the reader 
has access to the patch itself if they are interested in more details, and 
the commit message just needs to provide an overall guide to the patch 
with enough information for someone to decide whether to look at the patch 
itself), and given universal access to the version control history, the 
utility of a ChangeLog-format description is negative: the time required 
to produce a description split up at that level outweighs any benefits 
from any information therein that is not in the changeset-level 
description and is not simply a function of the diffs that could be 
generated automatically at the time of use.

As I've said, I don't object to shipping the changeset-level descriptions 
(e.g. the output of git log --stat) in tarballs, although I don't actually 
consider that particularly useful.  Or to having separate -with-history 
tarballs to archive the VCS history at the time of a release.

> If ChangeLogs isolate the GNU project some how, I don't know nor is it
> very relevant, it just moves the discussion from if they are useful or
> not to hypothetical speculation as to what people might or might not
> think about topics that can't be quantified.

The GNU Coding Standards should reflect good practice for the future free 
software environment, not the past.  Once they were ahead of their time, 
with principles such as avoiding the arbitrary limits that were common in 
the Unix tools of the time.  Now, ChangeLogs are behind current practice.  
We should *mandate* public version control.  We should *mandate* 
preserving the history if converting between version control systems.  We 
should *mandate* development discussions and bug tracking being public and 
archived.  All of those have been established good practice for a long 
time (and the GNU project provides hosting resources in the form of 
savannah for GNU packages needing such resources).  And we should 
recognize that with a DVCS, there is a better undo list of changes to the 
code than any ChangeLog could possibly provide.

> Linux is also a poor example to highlight how ChangeLog might
> hypothetically impede a project seeing that the maintainer is activley
> hostile towards our goals, and that Linux includes non-free software
> and why we have Linux-Libre

Linux is an excellent example when working on glibc at the 
kernel/userspace interface, where it's normal for changes involving a new 
syscall or other kernel interface to require work on both the kernel and 
glibc sides of the boundary and it ought to be easy for the same person to 
do the related work on both sides without unnecessary hoops to jump 
through - and the syscall interfaces in question don't involve any 
non-free software.  This is fundamentally different from e.g. code 
formatting where the different choices are both reasonable in current 
practice.

-- 
Joseph S. Myers
address@hidden