From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: ChangeLog styles (was: master 7e387c9: * lisp/man.el (Man-width-max): New defcustom (bug#32536, bug#9385)) Date: Mon, 09 Dec 2019 15:07:41 +0200 Message-ID: <83r21dd4v6.fsf@gnu.org> References: <83zhg2d78w.fsf@gnu.org> <87o8wize3e.fsf@mail.linkov.net> Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="165552"; mail-complaints-to="usenet@blaine.gmane.org" Cc: emacs-devel@gnu.org To: Juri Linkov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Dec 09 14:08:13 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1ieIlo-000gx7-I2 for ged-emacs-devel@m.gmane.org; Mon, 09 Dec 2019 14:08:12 +0100 Original-Received: from localhost ([::1]:39840 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ieIln-0005JP-8O for ged-emacs-devel@m.gmane.org; Mon, 09 Dec 2019 08:08:11 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:44175) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ieIlc-0005G7-97 for emacs-devel@gnu.org; Mon, 09 Dec 2019 08:08:01 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:60709) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ieIlb-00056Q-Mz; Mon, 09 Dec 2019 08:07:59 -0500 Original-Received: from [176.228.60.248] (port=4873 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1ieIlb-0007W5-2K; Mon, 09 Dec 2019 08:07:59 -0500 In-reply-to: <87o8wize3e.fsf@mail.linkov.net> (message from Juri Linkov on Sun, 08 Dec 2019 23:45:09 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 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.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:243258 Archived-At: > From: Juri Linkov > Cc: emacs-devel@gnu.org > Date: Sun, 08 Dec 2019 23:45:09 +0200 > > > P.S. And please do not "optimize" the log messages the way you did in > > this commit: it will make the generated ChangeLog entry look wrong. > > Please only use the ChangeLog-style text in the header line of the log > > entry if it is the entire text; otherwise please come up with some > > summary there, and leave the ChangeLog-style text in its original > > form, without an empty line in between. TIA. > > This is not optimization. The first line of this log message is > a complete sentence. It provides all information about the change, > answering the questions: WHERE and WHAT. > > WHERE: * lisp/man.el (Man-width-max) > > WHAT: New defcustom > > If even adds the references to bug reports: bug#32536, bug#9385 The ChangeLog entry that is produced from Git log of this commit should look like this: * lisp/man.el (Man-width-max): New defcustom (bug#32536, bug#9385) (Man-columns): New buffer-local variable. (Man-columns): New function. (Man-start-calling): Call Man-columns and set buffer-local Man-columns. (Man--window-state-change-timer): New internal variable. (Man--window-state-change): New internal function. (Man-fit-to-window): New function. (Man-mode): Add Man--window-state-change to local hook window-state-change-functions. This makes it clear that all the functions and variables you mention are from man.el. Your format leaves an empty line after the first one, so the connection to the file will be lost when we generate a ChangeLog from Git. This is the only problem I have with the format you used in this case. Everything else is very fine. > Many log messages don't provide the information about location of the > change in their subject, so it's difficult to guess what files are > affected by the change. There's no requirement in CONTRIBUTE to have all of that information in the heading line. In many cases it is simply impossible without losing too much of other useful information that describes the change. Putting the file name there, let alone the function/variable name and the bug number, eats up too much of precious estate, leaving too little for the description. I'm not saying that mentioning the location of the change there is "verboten", I'm saying it isn't required. > For example, such log subject provides no clue about the affected package: > > Fix documentation of '-position' server command > > It's not clear what is a server command it's talking about. > It takes additional efforts to output the full message to see > that actually it meant the package lisp/server.el. > Such subject would be much more clear: > > * lisp/server.el: Fix documentation of '-position' command Indeed, you have to read the entire log message to know which file(s) were modified, and that's expected. It is so even in your case: the second file that you modified is not mentioned in the header line (and shouldn't be). Thanks.