From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail
From: Jim Porter <jporterbugs@gmail.com>
Newsgroups: gmane.emacs.devel
Subject: Re: master 9ccaa09a635: ; .dir-locals.el (log-edit-mode)
 <fill-column>: Set to 64.
Date: Thu, 8 Feb 2024 09:49:41 -0800
Message-ID: <19ce18d6-3754-c755-2b1b-5fa15734b63c@gmail.com>
References: <170727415485.32408.11264518274307262467@vcs2.savannah.gnu.org>
 <20240207024915.38686C0EFEC@vcs2.savannah.gnu.org>
 <CADwFkmmK+r6Q_GdTa++PaZRm3ngQ_ueXR2yfzN8RaS607dUiOg@mail.gmail.com>
 <87plx74u0i.fsf@yahoo.com> <0e8b1009-1491-2fb7-9efc-c415ed66d334@gmail.com>
 <87a5ob4ok3.fsf@yahoo.com> <62ce63d3-76ce-b511-b2bf-27eb526bb711@gmail.com>
 <8634u3xvuq.fsf@gnu.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214";
	logging-data="24448"; mail-complaints-to="usenet@ciao.gmane.io"
Cc: luangruo@yahoo.com, stefankangas@gmail.com, emacs-devel@gnu.org
To: Eli Zaretskii <eliz@gnu.org>
Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Feb 08 18:50:34 2024
Return-path: <emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org>
Envelope-to: ged-emacs-devel@m.gmane-mx.org
Original-Received: from lists.gnu.org ([209.51.188.17])
	by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org>)
	id 1rY8Xh-0006As-Kb
	for ged-emacs-devel@m.gmane-mx.org; Thu, 08 Feb 2024 18:50:33 +0100
Original-Received: from localhost ([::1] helo=lists1p.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.90_1)
	(envelope-from <emacs-devel-bounces@gnu.org>)
	id 1rY8Ww-0005t2-LC; Thu, 08 Feb 2024 12:49:46 -0500
Original-Received: from eggs.gnu.org ([2001:470:142:3::10])
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <jporterbugs@gmail.com>)
 id 1rY8Wu-0005st-T8
 for emacs-devel@gnu.org; Thu, 08 Feb 2024 12:49:44 -0500
Original-Received: from mail-pg1-x529.google.com ([2607:f8b0:4864:20::529])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
 (Exim 4.90_1) (envelope-from <jporterbugs@gmail.com>)
 id 1rY8Ws-0001ly-SC; Thu, 08 Feb 2024 12:49:44 -0500
Original-Received: by mail-pg1-x529.google.com with SMTP id
 41be03b00d2f7-5d42e7ab8a9so1364845a12.3; 
 Thu, 08 Feb 2024 09:49:42 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=gmail.com; s=20230601; t=1707414581; x=1708019381; darn=gnu.org;
 h=content-transfer-encoding:in-reply-to:from:references:cc:to
 :content-language:subject:mime-version:date:message-id:from:to:cc
 :subject:date:message-id:reply-to;
 bh=+Qz4WHoO401mpSC3gxHrgtls37yH6RhYskR5PmhVPH4=;
 b=TgvaB9BinmgMJ8XODq9Z6SS1raqD/N/bSiuYW0RkyqP0amGteuf8d5bdwzfRknWd+3
 nsZP0XNSzt1oP4zAOt7eejdE8biifl34Izix9o6D5SC/mH2OX30wb0XYjY2AT6Kj37C8
 EfMuXxMrUbs2svEbQ/TsmpHApuEFlRGCTwb7pfGceIQM8GXOYmCetl89cBUb3+2LNXpT
 jer26sMc1Fav934cymlY9Jk1PF1HEVn88Y0mWklM3rLWUYZdb39MT4MzzTWTl81iQSi6
 BhU0pihgpE/MHWm3mmff7KYioePzHRf2dFYOcHAvt3dIDIX0f/mISZT6aNfCA+D5r6fh
 SkSA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20230601; t=1707414581; x=1708019381;
 h=content-transfer-encoding:in-reply-to:from:references:cc:to
 :content-language:subject:mime-version:date:message-id
 :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to;
 bh=+Qz4WHoO401mpSC3gxHrgtls37yH6RhYskR5PmhVPH4=;
 b=Dyl8dohEaFFOFg9LTmibRcOo5BL2JnsbIiqH6O+4jPV+dHR+rLyQdi8ExJnIkjJGkm
 Yy9mjyZxptirFHTyUArNOA+eZrOTPYApx3hn+R0FpsFAx6nTML8EQdvhP/ebX3vMdSNY
 9DcX82XDC1VXgo6W96jOHVi4fHRNmadl5zoPlBKBNzfrdcnKWCEi6BI9dvxTsA7fSjWw
 iy6P+WaF58ZZAvFyvn8INn8PjkiWEUifJRPX++qFbwsNZgH7IguCR98fUp+Tq8IRi2RK
 9GoSXVvPLJQ1uwKV0WtdPBBIArpFoTZ7LP+OJY9qHL3i7ufA3eAE7FZnoGRZ/Wfxt0wt
 bH4A==
X-Gm-Message-State: AOJu0YxX22V9yqOpQHL+g+iojjW+2MvO16EKDHD7+jiWcWvRK0y8rWbq
 Yfre2Ub63i649l9EYqyEo4cTjS+ntUFCnztVh8u33gOZHac6GkjYvOxUcrYH
X-Google-Smtp-Source: AGHT+IHalqIgILIWQGICzL4OCejYHbd0Ac8tKdqJdA4+/ea9ihpQBEqHVqGozZYIMvGypnbFdvyGzg==
X-Received: by 2002:a17:90b:1898:b0:296:7bc3:7597 with SMTP id
 mn24-20020a17090b189800b002967bc37597mr6872256pjb.17.1707414580971; 
 Thu, 08 Feb 2024 09:49:40 -0800 (PST)
X-Forwarded-Encrypted: i=1;
 AJvYcCVy/8C/gIllTMy9kQgyE/82GAXETD1wbFMN9SwGNti0C04Dw/GttBEBf6jNqxAaQy7a+7qvWYD78ZJbLWGI1YBpCQyE3BGdg3OmmJ7ZMe0iCX29/V8fda07qZyV
Original-Received: from [192.168.1.2] (076-168-148-233.res.spectrum.com.
 [76.168.148.233]) by smtp.googlemail.com with ESMTPSA id
 ee5-20020a17090afc4500b0028d70a8d854sm22613pjb.54.2024.02.08.09.49.40
 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128);
 Thu, 08 Feb 2024 09:49:40 -0800 (PST)
Content-Language: en-US
In-Reply-To: <8634u3xvuq.fsf@gnu.org>
Received-SPF: pass client-ip=2607:f8b0:4864:20::529;
 envelope-from=jporterbugs@gmail.com; helo=mail-pg1-x529.google.com
X-Spam_score_int: -20
X-Spam_score: -2.1
X-Spam_bar: --
X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
 DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001,
 RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001,
 T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-BeenThere: emacs-devel@gnu.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: "Emacs development discussions." <emacs-devel.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-devel>,
 <mailto:emacs-devel-request@gnu.org?subject=unsubscribe>
List-Archive: <https://lists.gnu.org/archive/html/emacs-devel>
List-Post: <mailto:emacs-devel@gnu.org>
List-Help: <mailto:emacs-devel-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-devel>,
 <mailto:emacs-devel-request@gnu.org?subject=subscribe>
Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org
Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org
Xref: news.gmane.io gmane.emacs.devel:316045
Archived-At: <http://permalink.gmane.org/gmane.emacs.devel/316045>

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

With the first and last sentences, I think this means that one commit 
message will become one ChangeLog entry. (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".

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." 
That's not consistent with the above, IMO.

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.

> - Explaining the rationale for a design choice is best done in comments
>   in the source code.  However, sometimes it is useful to describe just
>   the rationale for a change; that can be done in the commit message
>   between the summary line and the file entries.

Here again, now the documentation calls these file/function change 
descriptions "file entries". (It's also talking about the reasoning for 
adding a descriptive paragraph, which I think would be helpful up above 
when it's originally mentioned.)

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?

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