Re: master 9ccaa09a635: ; .dir-locals.el (log-edit-mode) <fill-column>: Set to 64.

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 8 Feb 2024 09:49:41 -0800
> Cc: luangruo@yahoo.com, stefankangas@gmail.com, emacs-devel@gnu.org
> From: Jim Porter <jporterbugs@gmail.com>
> 
> On 2/7/2024 11:23 PM, Eli Zaretskii wrote:
> > Please try to tell in more detail what confused you.  I don't want to
> > make any significant change in CONTRIBUTE, since the current text is
> > the result of many people reading it and commenting on its text.  So
> > I'd prefer to make the minimal required changes, not rewrite whole
> > passages anew.
> 
> Sure thing. As I read it, the "Commit messages" section uses the phrase 
> "ChangeLog entries" in two different senses. First is this passage:
> 
> > Ordinarily, a change you commit should contain a log entry in its
> > commit message and should not touch the repository's ChangeLog files.
> [...]
> > Occasionally, commit messages are collected and prepended to a
> > ChangeLog file, where they can be corrected.

These talk about "ChangeLog files", not "ChangeLog entries".  So they
are about a different aspect.

> >   If the summary line starts with a semicolon and a space "; ", the
> >   commit message will be ignored when generating the ChangeLog file.
> >   Use this for minor commits that do not need separate ChangeLog
> >   entries, such as changes in etc/NEWS.

This indeed talks about "ChangeLog entries", and correctly so.

> With the first and last sentences, I think this means that one commit 
> message will become one ChangeLog entry.

There's nothing in the text which says that.  (Not that I think it's
important, since the text always talks about "entries", plural, and
never in singular, so whether it's a single file or several doesn't
seem to matter, for the purposes of what this text attempts to convey
and explain.)

> (Here, I'm mainly concerned with the terminology, since I know
> roughly what happens in the code.)  That's consistent with the GNU
> Change Log manual[1], which describes it as, "an individual change
> or the smallest batch of changes that belong together".

The language of the GNU manual is not relevant here, since this text
is not about ChangeLog files.

> Later, in the section about how to format a commit message is this:
> 
> > - Unindented ChangeLog entries normally come next.  However, if the
> >   commit couldn't be properly summarized in the brief summary line,
> >   you can put a paragraph (after the empty line and before the
> >   individual ChangeLog entries) that further describes the commit.
> 
> This, and other bullet points are all talking in the context of a single 
> commit. But this paragraph talks about multiple ChangeLog entries within 
> one commit (*after* the summary line and descriptive paragraph). After 
> carefully reading this, I think it means that one ChangeLog entry is a 
> line of the form "* some/file.el (function): Frobnicate the widget." 

Yes.  But where did you see any verbiage to the contrary?

> That's not consistent with the above, IMO.

I fail to see how it could be inconsistent, FWIW.

> After this paragraph is where I finally got things mixed up in the 
> current discussion: "Lines in ChangeLog entries should preferably be not 
> longer than 63 characters..." This again says "ChangeLog entries", and I 
> initially read that in the first sense: "the ChangeLog entry is the 
> commit message that's been inserted into the ChangeLog file". Since 
> those messages are ultimately indented by one tab, that would affect how 
> many columns you can fill to within the (raw, unindented) commit 
> message. Whether you should count that tab is what ultimately confused me.
> 
> (When carefully re-reading this paragraph, I think it means that each 
> ChangeLog entry is a single file/function change description, not the 
> whole message.)
> 
> There are a couple of other cases where the terminology seems 
> inconsistent to me:
> 
> > - If only a single file is changed, the summary line can be the normal
> >   file first line (starting with the asterisk).
> 
> Here, the documentation talks about the "file first line", but that 
> sounds like the same text that the paragraph about "Unindented ChangeLog 
> entries" refers to.

My conclusion from this is that we should simply use "ChangeLog
entries" everywhere where we mean it.  So I've now changed CONTRIBUTE
to use that consistently, avoiding alternative equivalent terminology
that succeeded to confuse you.

> In conclusion, it seems to me that "ChangeLog entry" can mean two 
> different things depending on what part you're reading, and we're not 
> using a consistent name for the lines like "* some/file.el (function): 
> Frobnicate the widget." How about calling those lines "file entries" 
> everywhere?

I prefer to call them "ChangeLog entries", since that's what we were
using, by and large, with a small number of exceptions, which are now
gone.