Re: What is our ChangeLog management policy?

[Keith Marshall]

On 05/09/2021 18:34, Ingo Schwarze wrote:
> Keith Marshall wrote on Sun, Sep 05, 2021 at 04:49:41PM +0100:
> 
>> 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.
> 
> I like this proposal very much, and more than anything else proposed in
> this thread so far.

Thanks, Ingo!

> While i do see the point in the three-tier system outlined by Branden,
> let me note that it causes more work for developers, which is not ideal
> for a small development team with little time to spare.  Also, Branden
> himself pointed out that is is not easy to implement consistently even
> when developers apply great diligence.

Right.  It seems way too convoluted, to me.

> I think having full details in one place is important, and guessing
> from what Keith, Branden, and myself said, it might be possible to
> reach consensus that git commit messages are a good place for that.

I can agree to that.  In fact, my own work-flow starts with a patch
series, managed by Mercurial Queues; for each patch, I compile a
complete ChangeLog entry within the patch header, which means that, by
default, it will become the commit message when the patch is finalized
for commit -- it requires extra effort to duplicate it into a separate
ChangeLog file, where it becomes redundant anyway.

> The uppermost layer described by Branden, the release notes in the
> NEWS file, provided for users at large, also matter.

Sure, they do; however, that's an entirely orthogonal issue, to what is
incorporated into a commit message, or any separate ChangeLog file.

> But having an intermediate layer between the two for
> "packagers/expert users" seems less important to me.  I suspect good
> commit messages can serve the needs of "packagers/expert users" just
> as well as the needs of groff developers.

If the ChangeLog entry, (in a separate file), is a verbatim copy of the
commit message, I simply cannot see what benefit the separate ChangeLog
file might offer.

> If we decide to implement Keiths proposal, making the change at the
> same time as the next GNU troff release would seem ideal to me.
> That would make communication simple and straightforward:
> "The ChangeLog goes up to groff X.Y.Z; after that, look at the git
> commit messages."

Seems reasonable, but how long are we going have to wait for that next
release?  I would really like to move my commits to a rational policy,
sooner rather than later.

-- 
Regards,
Keith.