Re: What is our ChangeLog management policy?

[G. Branden Robinson]

At 2021-09-05T14:25:14+0200, Ingo Schwarze wrote:
> Keith Marshall wrote on Sat, Sep 04, 2021 at 10:32:05PM +0100:
> > I see a complete lack of consistency in this.  Some commits
> > duplicate the entire ChangeLog entry in the ChangeLog file, and in
> > the Git log message; some update the ChangeLog file, but use only a
> > summary line as the Git log message, while some place the entire
> > ChangeLog entry into the Git log message, but do not touch the
> > ChangeLog file at all.
> 
> Uh oh.  I fear this may have been triggered by my recent commit
> to tmac/mdoc/doc-syms, which i considered so minor that i thought
> a ChangeLog entry would be nothing but noise.

Huh.  I assumed it was a complaint about _my_ ChangeLog/commit message
practices, but wasn't sure how to respond.

For what it's worth, I hammered out my practices for groff along these
lines by consulting with Werner, Ingo, and others on this list a few
years ago.

Some of what I commit is restyles and recasts of documentation,
including comments in source files and string literals used in
diagnostic messages.  The consensus appeared to be that these sorts of
changes didn't "rise" to the level of ChangeLog-ability--only a syntax
goof could possibly affect "behavior" or code flow in such changes.

Another thing that I regard as often not warranting a record in the
ChangeLog are tweaks to our test cases.  I've written most of the 80
tests scripts that are now present but my views about how best to
structure them and what shell idioms are best to use have seen some flux
over the years.  Test cases are developer-facing, not user-facing, so I
regard this as within the spirit of the ChangeLog.  (Sometimes, though,
a logic change forces a change to a test, sometimes even an "unrelated"
one, and I have no shame about letting this information "leak" into the
ChangeLog; a user might be curious about how we adapted to our own
logic change.  Admittedly, test scripts are usually not shipped in
binary distributions, but at least people will know the change exists to
be found--say, in our Git repository.)

The next level up are changes that do warrant logging in the ChangeLog.
They constitute everything you'd read about in the GNU Coding Standards
on this subject[1].  An important distinction that creeps in at this
point, and which I have goofed up in the past but then gone back to fix,
is that groff has sub-projects (not in the Git sense) in the contrib/
directory.  In theory any of these could be "spun out" and resume an
independent life outside of the groff Git repository at any time.  To
preserve this possibility and out of courtesy to these projects'
authorship and conceptual independence, they carry dedicated ChangeLogs
that are separate from of the one at the root of the groff tree.
Generally, changes made to a contrib/ project are not logged in the root
ChangeLog and changes made to anything not in contrib/ don't appear in
one of the contrib/ ChangeLogs.  (However, occasionally a broad change
is made, and "evidence" of these projects' maintenance as part of groff
"leaks" into their dedicated ChangeLog files.  As that's simply a matter
of historical fact, I don't regard it as a problem.)

A further qualification for placement in a ChangeLog file is that if
something deals with a Savannah ticket, it gets mentioned there.
Sometimes stuff that would not otherwise qualify for such placement gets
into the ChangeLog file for that reason, like typo fixes in the manuals.
(I can't promise I've been 100% consistent about this, however.)  The
rationale for this is that something that got noticed by someone who is
not a groff committer and filed as a Savannah ticket probably got
noticed by other people as well, and it's the kind of thing that might
crop up in Web searches.  We therefore want to make the resolution of
that problem relocatable.

Another specimen is a documentation/diagnostic message/code comment fix
that would ordinarily be in the "commit message only" category but
corrects an outright error or false claim of material consequence to a
reader's understanding of these things.  Those are bad enough that in my
opinion they would warrant a Savannah ticket, but usually when I'm the
one who notices them, I'm too lazy to execute that procedure, so I just
fix the problem and place a notice of it in the ChangeLog.  These are
easy to spot because I typically say something like "Fix error:" and/or
explain the confusing point in the ChangeLog entry, whereas the I use
the word "nit" to refer to most of the stuff in the commit message-only
category.

At the highest level are changes that warrant not only a ChangeLog entry
but discussion in the NEWS file.  Since that's not squarely on topic
I'll pass over that for now.

Most of the time my commit messages are a re-indented and reflowed
version of what I put in one ChangeLog file or another (re-"path"ed as
well, for contrib/ stuff).  Sometimes, though, I add further information
in the commit message that is strongly developer-facing.  When I add
a regression test, I typically do so in advance of the fix for the
problem the test exposes, to demonstrate that the test detects the
problem.  In my experience, this is widely regarded as a best practice.
However, it does run counter to another best practice, which is "never
make the tree go red" (i.e., the tip of the master branch should always
be in a buildable state, as close to production-ready as possible,
barring some very good reason for it not to be).  So I annotate commits
with warnings that the new test will cause a test failure, and that
means "make check" will probably exit nonzero.  On several occasions
these have been an aid to myself when I do a "git bisect" and feel a
surge of dismay when I see that the tree wasn't "green" at a past date.

Finally, I sometimes put developer-facing asides, speculations, or
requests for feedback or correction in a commit message (only).  It
almost never happens that anyone responds to these, but that is what
they are there for.  Usually these are at the end of the message, after
the obvious copy of ChangeLog material (if any).

I don't execute any of the above principles with perfect fidelity, which
is a source of frustration to me, but the above reflects my intentions
and, I hope, makes my practices intelligible.

> > Personally, I think the complete duplication in both ChangeLog file,
> > and in Git log message, is gross overkill.  In those projects, (e.g.
> > MinGW), which I manage personally, if a sub-project already has a
> > ChangeLog file, then I ask committers to write a full ChangeLog
> > entry, including a suitable summary line, into the ChangeLog file,
> > and duplicate ONLY the summary line as the Git log message.
> 
> I would dislike that rule.  I think having full details in the commit
> message is extremely valuable because modern tools like git(1) as well
> as git web frontends make inspecting commit histories very simple and
> powerful, and not having full information in there would be highly
> inconvenient: having to inspect an additional plain-text file with
> much less intrinsic structure would be a bother.  Actually, the same
> even applies to tools that some may consider semi-modern at best, like
> CVS and SCCS...

I would also note that Werner Lemberg explicitly expressed a preference
against for the practice Keith proposes.  In time I've come to see the
wisdom of it.  I envision of rough trichotomy of correspondence.

        NEWS                    all users
        ChangeLog               packagers/expert users
        commit messages         groff developers

The volume of information grows at each level, but so does the amount of
attention paid to groff by the corresponding audience.  For most people,
groff is just a thing behind the scenes that formats man pages, and many
of them don't know even that much about it.

If anyone has any screw-ups of mine they'd like to bring to my attention
that are correctable and which I haven't, please do so.

Regards,
Branden

[1] https://www.gnu.org/prep/standards/standards.html#Change-Logs

signature.asc
Description: PGP signature