From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Jim Porter Newsgroups: gmane.emacs.devel Subject: Re: master 9ccaa09a635: ; .dir-locals.el (log-edit-mode) : 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> <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 Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Feb 08 18:50:34 2024 Return-path: 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 ) 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 ) 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 ) 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 ) 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." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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: 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