Re: What is our ChangeLog management policy?

[Keith Marshall]

On 05/09/2021 14:42, G. Branden Robinson wrote:
> 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.

Actually, it was neither -- it was simply a plea for consensus on an
agreed policy -- something which seems to be conspicuous by its current
absence -- which I may adopt for _my_ commits.

> 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.
> 
> [...snip...]
> 
>>> 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.

Huh?  What proposal is that?  I've outlined two distinct policies, which
are applied in a project which I manage; I'm not proposing that either
of them, in particular, is what groff should adopt.

If you would like my proposal, then it would be that we make one final
commit, for each extant ChangeLog file, in which we add a log message to
the effect that free-standing ChangeLog files are deprecated, and that
the details of future commits will be found _exclusively_ in the Git
log.  Then, we insert the entire content of what we would have added to
the ChangeLog file as the Git log message.  IMO, it is anathema that the
log message content should be redundantly duplicated in a free-standing
ChangeLog file -- there are perfectly adequate tools, for generation of
such a free-standing file, in GNU ChangeLog format if desired, directly
from the Git log, for any user who wishes to extract it in that form.
(Alternatively, as Ingo has pointed out, there are web viewers -- and
Savannah's is among the better of these -- which render a perfectly
accessible view of the ChangeLog info, again directly from the Git log).

-- 
Regards,
Keith.