Whither changelogs

[G. Branden Robinson]

At 2021-10-05T08:56:24+0100, Keith Marshall wrote:
> Seriously, Branden?
> 
> On 03/10/2021 14:20, G. Branden Robinson wrote:
> > gbranden pushed a commit to branch master
> > in repository groff.
> > 
> > commit fc6989ae19146294bcf27d08453c6005a8b363c5
> > Author: G. Branden Robinson <g.branden.robinson@gmail.com>
> > AuthorDate: Sun Oct 3 22:48:48 2021 +1100
> > 
> >     ChangeLog: Wrap long lines.
> 
> Why do you waste your time, indulging in such asinine whimsy?  Why
> introduce a commit which contributes absolutely zero value?

I object to your characterization, but I do it because excessively long
lines disrupt my workflow.

> The ChangeLog entry, which you modified, was already 100% compliant
> with established GNU convention; I know this, because it was I who
> wrote it.

> I know that the lines were NOT excessively long, because I edited it in
> vim, with the default filetype plug-in for changelog active; this
> GUARANTEES that the lines are wrapped to a sane length (78 chars max),
> which is consistent with GNU convention.

Why is Vim, or this plugin you speak of, disregarding the modeline at
the bottom of the file?

##### Editor settings
Local Variables:
fill-column: 72
mode: change-log
version-control: never
End:
vim:set autoindent textwidth=72:

"textwidth" is not a new feature; as best I can recall, it goes back to
the 1990s.  (Vim works for me, and "set colorcolumn=+1" in my
$HOME/.vimrc makes overlong lines plainly visible.)

> Pursuant to our recent discussion regarding ChangeLog files, if you
> are going to indulge in such futility, why should I even bother to
> update the ChangeLog at all?  I may as well just provide the detail in
> the git commit message, and delegate the ChangeLog file update
> entirely to you.

I can live with that.  Since it evidently needs to be said, I'm not
setting out to annoy you.

> The sooner we deprecate free-standing ChangeLog files, the better,
> IMO.

My resistance this idea lies in the fact that people err, including in
commit messages, but commit messages are set in stone once pushed
(because Merkle trees).  Many is the time I've gone back and fixed a
thinko in a ChangeLog entry I wrote.

A ChangeLog is a vehicle for developer-to-developer (or
developer-to-sophisticated-user) communications.  Like nearly any other
document, it needs to be subject to revision for correction of errata,
bearing in mind that its purpose is to log changes.  If you misdescribe
the change you have made, you should be able to fix such a misstatement
in some place less ephemeral than a mailing list or Discord channel.

The discard of ChangeLogs that are subject to revision encourages two
forms of vice in use of commit messages, in my experience.

1. They discourage conscientious developers from saying what should be
   said, for fear of committing an uncorrectable error, particularly one
   that would mislead their colleagues.  This adds unnecessary friction
   to development.

2. They reward non-conscientious developers for neglecting discipline in
   the composition of their commit messages.  If something's wrong,
   tough--nothing anyone can do about it.  Adjust the cowboy hat and
   ride roughshod to (and likely over) the next task.

All of that said, I'm not particularly enamored of the GNU ChangeLog
format myself; I try to hew it out of respect for the continuity of the
groff project and because it is broadly understand.  You might have
noticed that I slightly reformat the entries when I migrate them to my
commit messages (while this might seem pointless to some, it affords me
an additional opportunity to review my own words and I do sometimes
catch and correct mistakes this way).

I certainly have not mastered all the little sigils I'm supposed to use
for bracketing of various items (the GNU Coding Standards assign meaning
to all of (), [], and <>[1], and the C/C++-centric basis of the
Standards leaves me uncertain sometimes how to apply them to *roff files
or documentation files.  I have assumed, since no one as taken me to
task on one of these points as you did on this one, that people are
either uncertain themselves, find my uses suitable enough, or don't
regard them as rising to the level of objectionability.  When unsure, I
try to err on the side of clarity.

Sometimes clarity comes only after I've pushed a change, which is why I
advocate revisable ChangeLogs.

At any rate, is it too much to ask you to troubleshoot the Vim plugin
you're using to make it stop disregarding "textwidth=72"?

Regards,
Branden

[1] I also have doubt whether Vim's syntax file for the GNU ChangeLog
    format is well-polished; for example, it highlights small integers
    and the word "may" as if they were parts of a date string in
    inappropriate places, and I suspect, though I am not sure, that it
    is sloppy about when parentheticals are file name references.  But
    as far as I know no one has promulgated a formal grammar for the GNU
    ChangeLog, and if an unofficial one exists, perhaps access to it is
    restricted to parishioners of the church of Emacs, and not shared
    with pagan vi users.

signature.asc
Description: PGP signature