Re: What is our ChangeLog management policy?

[Ingo Schwarze]

Hi Keith,

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.

> 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...

> For newer projects, we dispense
> with the ChangeLog file altogether, and write the entire ChangeLog entry
> as the Git log message.  (In the latter case, I have a mercurial plug-in
> to extract a free-standing ChangeLog, on-the-fly, from the Git log -- I
> use hggit to work with git repositories).

I like that idea, and in my personal projects, i use cvs2cl(1) for
that purpose.

> FWIW, I've been following the former MinGW policy for my recent groff
> commits, but I would be happy to adopt any alternative agreed policy; I
> do not think that the present inconsistencies should, in any way, be
> considered desirable.

You are probably right about that.

Yours,
  Ingo