on change logs (was: [BUG] man(7) page not showing footer)

[G. Branden Robinson]

Hi Alex,

At 2022-11-02T13:39:58+0100, Alex Colomar wrote:
> Heh, I've been reading the patch, and it very much sounds like Chinese
> to me.  Good that it was easy for you :)

Not _too_ easy; the second part of the patch was spurious.  I managed to
confuse myself.  (It's _static_ register and string interpolations,
i.e., those performed at macro definition time, that are incompatible
with `ec`/`eo` bracketing, not dynamic ones.  The latter is the common
case.)

> I'll get it from git soon.  I'm not in a hurry for it ;)

A good thing too.  Incidentally this is one reason I don't push every
day even though I work on groff almost every day.  After 24-72 hours I
often realize that some change I have made is boneheaded, and I revise
it or back it out.

> I wonder why so much duplication.  The ChangeLog seems like an exact
> _duplicate_ of the git history.

It's a subset.  I am continuing the practice that I was trained on when
I joined groff development.  It wasn't written down anywhere except
emails, though.  I've since added a HACKING file and documented it.

https://git.savannah.gnu.org/cgit/groff.git/tree/HACKING

I also suffix a commit message with asides, mentions of miscellaneous or
auxiliary changes (usually to the style of text prose), or illustrative
exhibits of formatter behavior before and/or after the change.  This
material I do _not_, as a rule, copy into the commit message.

> I chopped the Linux man-pages 'Changes' file considerably by having a
> high level overview of the changes, and deferring to git(1) for
> further details.

There are some groff contributors who are vocally opposed to the
practice.  After some initial frustration with it, while I found a
workflow that suited me (and discovering that Werner is a reliable
source of good advice), I have come to see it as useful.  Setting aside
the stuff that is documented _only_ in commit messages (documentation
tweaks, cosmetic code changes), a proper ChangeLog file has virtues.

1.  It's available, or is required to made available on request, to all
    who receive the software.  This is explicit in GNU GPLv2, §2.

    "a) You must cause the modified files to carry prominent notices
    stating that you changed the files and the date of any change."

    This provision dated to a time when change logs were maintained on a
    per-file basis, usually in a whopping big comment block at the top
    of the file.  A GNU-style ChangeLog file honors the spirit of the
    foregoing provision.  I seem to remember that during the GPLv3
    drafting process, this requirement was uncontroversially revised to
    reflect common practice even in GNU projects and the supersession of
    file-based revision control systems (SCCS, RCS) by hierarchical ones
    ("repositories").

    I can't find the updated language in GPLv3 at a quick glance, but I
    don't regard that as determinative; the GNU GPL was written to
    codify and promote good _social_ practices of software sharing.
    We've had 25 years to observe the results when people hew to them
    only grudgingly.  Ideally, people who hate copyleft would stick to
    their BSD and MIT licenses while chasing their dreams of mixing a
    little secret, proprietary sauce into free code and thereby living
    out their days on a yacht sustained by the glorious extraction of
    monopoly rents.  Of course that is a utopian perspective; the modus
    operandum of a rentier is to find new and vibrant social contracts
    to join and defect from in swift succession, maximizing gains.  If a
    community doesn't survive such predation, those defectors who have
    read a little Schumpeter (perhaps at Nth hand) will characterize
    their actions as "creative destruction".

2.  It's mutable; commit messages are not, but people make mistakes.  I
    make mistakes all the time.  Typos and even occasional errors of
    fact get into my commit messages, and moreso because, unlike some, I
    am not committed to terseness above all other virtues.  It is easy
    to write a useless commit message, and easier still to tell oneself
    that one is thereby upholding the elegant traditions of Unix and C.

    If we restrict the legitimate purpose of a ChangeLog entry or commit
    message only to the "what" of a change set, then you don't need it:
    a diff suffices to tell you _what_ changes were made.  Commit
    messages, like code comments, should be concerned with "what"
    insofar as doing so enables clear expression of the more important
    matter of _why_ changes were made.  I try to explain the changes I
    make, both so I can defend myself in the arguments that occasionally
    arise in software development, and more fundamentally so that I can
    later _remember_ why I made them.

    Human brains can be slick surfaces.  I often find I have to modify
    an old ChangeLog entry (usually one of my own) to clarify or correct
    it, usually to explain what _really_ changed or what _actual_ facts
    obtained at the time, instead of the ones I deludedly believed at
    the time I first wrote it.

    I will note that I generally don't _retrospectively_ revise others'
    ChangeLog entries.  (I may help compose them as part of an initial
    commit.)  If I find commentary is essential for honest communication
    with the users, I tend to put it in brackets and sign it with my
    initials.

I hope this sheds some light on things.  I know you asked for it earlier
and I didn't have the wherewithal to write all this down at the time.
Other projects don't necessarily need to follow the same practices; the
foregoing is my defense of existing practice in groff, which has the
virtue of long continuity.

I can say I'm very much looking forward to retiring the current
ChangeLog file to ChangeLog.123.  Its length could be considered
embarrassing. 😅

Regards,
Branden

signature.asc
Description: PGP signature