File names in ChangeLog entries

File names in ChangeLog entries

[Stefan Kangas]

Please in the future can everyone take care to use the following file
name format in ChangeLog entries:

    * lisp/play/tetris.el: Foo.

Do not use any of these formats:

    [not the full file name:]

        * tetris.el: Foo.

    [missing suffix:]

        * lisp/play/tetris: Foo.

    [wrong suffix:]

        * doc/lispref/emacs.text: Foo.

    [not supported by our tools - patches welcome:]

        * lisp/play/{tetris,morse}.el: Foo.

    [last file not full file name]

        * etc/play/tetris.el, morse.el: Foo.

I recommend using `add-change-log-entry-other-window' bound to `C-x 4 a'
to get this right.

I've had to spend quite some time fixing up ChangeLog entries in
preparation of the Emacs 28 pretest, and as you can imagine this work is
both manual and time consuming.

Thanks in advance.

Re: File names in ChangeLog entries

[Philip Kaludercic]

[-- Attachment #1: Type: text/plain, Size: 231 bytes --]

Stefan Kangas <stefan@marxist.se> writes:

> I recommend using `add-change-log-entry-other-window' bound to `C-x 4 a'
> to get this right.

As I use C-c C-w in log-edit, I would appreciate it if a patch like this
could be merged:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Use-VC-relative-file-names-in-ChangeLog-entries.patch --]
[-- Type: text/x-patch, Size: 1285 bytes --]

From f3f87cab56d1bc1754d9e83a9dd53d0cb48c02b0 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Tue, 30 Nov 2021 21:05:42 +0100
Subject: [PATCH] Use VC-relative file names in ChangeLog entries

* lisp/vc/diff-mode.el (diff-add-log-current-defuns): Check
vc-root-dir to prepend the project path to the file being modified.

See https://mail.gnu.org/archive/html/emacs-devel/2021-11/msg02195.html
---
 lisp/vc/diff-mode.el | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/lisp/vc/diff-mode.el b/lisp/vc/diff-mode.el
index 057ffcd06e..40749754d8 100644
--- a/lisp/vc/diff-mode.el
+++ b/lisp/vc/diff-mode.el
@@ -2343,7 +2343,10 @@ diff-add-log-current-defuns
           ;; hunks (e.g., "diff --git ..." etc).
           (re-search-forward diff-hunk-header-re nil t)
         (setq hunk-end (save-excursion (diff-end-of-hunk)))
-        (pcase-let* ((filename (substring-no-properties (diff-find-file-name)))
+        (pcase-let* ((filename (substring-no-properties
+                                (file-relative-name
+                                   (diff-find-file-name)
+                                   (vc-root-dir))))
                      (=lines 0)
                      (+lines 0)
                      (-lines 0)
-- 
2.34.0


[-- Attachment #3: Type: text/plain, Size: 130 bytes --]


(Something is currently wrong with my Savannah account so I wouldn't be
able to push the change myself).

-- 
	Philip Kaludercic

Re: File names in ChangeLog entries

[Philipp Stephani]

Am Di., 30. Nov. 2021 um 20:21 Uhr schrieb Stefan Kangas <stefan@marxist.se>:
>
> Please in the future can everyone take care to use the following file
> name format in ChangeLog entries:
>
>     * lisp/play/tetris.el: Foo.
>
> Do not use any of these formats:
>
>     [not the full file name:]
>
>         * tetris.el: Foo.
>
>     [missing suffix:]
>
>         * lisp/play/tetris: Foo.
>
>     [wrong suffix:]
>
>         * doc/lispref/emacs.text: Foo.
>
>     [not supported by our tools - patches welcome:]
>
>         * lisp/play/{tetris,morse}.el: Foo.
>
>     [last file not full file name]
>
>         * etc/play/tetris.el, morse.el: Foo.
>
> I recommend using `add-change-log-entry-other-window' bound to `C-x 4 a'
> to get this right.

That almost never does the right thing for me, though. It almost
always tries to create a ChangeLog file in a subdirectory (e.g.
"lisp") and makes the filenames relative to that subdirectory, and I
then have to fix them manually.

Re: File names in ChangeLog entries

[Stefan Kangas]

Philipp Stephani <p.stephani2@gmail.com> writes:

>> I recommend using `add-change-log-entry-other-window' bound to `C-x 4 a'
>> to get this right.
>
> That almost never does the right thing for me, though. It almost
> always tries to create a ChangeLog file in a subdirectory (e.g.
> "lisp") and makes the filenames relative to that subdirectory, and I
> then have to fix them manually.

It always worked for me, besides having to fix up the formatting
(removing the extra tabs for the git commit message).

Does that happen to you also in "emacs -Q"?

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 30 Nov 2021 15:24:00 -0800
> Cc: Emacs developers <emacs-devel@gnu.org>
> 
> Philipp Stephani <p.stephani2@gmail.com> writes:
> 
> >> I recommend using `add-change-log-entry-other-window' bound to `C-x 4 a'
> >> to get this right.
> >
> > That almost never does the right thing for me, though. It almost
> > always tries to create a ChangeLog file in a subdirectory (e.g.
> > "lisp") and makes the filenames relative to that subdirectory, and I
> > then have to fix them manually.
> 
> It always worked for me, besides having to fix up the formatting
> (removing the extra tabs for the git commit message).

It also works for me.

Re: File names in ChangeLog entries

[Andreas Schwab]

On Nov 30 2021, Philipp Stephani wrote:

> That almost never does the right thing for me, though. It almost
> always tries to create a ChangeLog file in a subdirectory (e.g.
> "lisp") and makes the filenames relative to that subdirectory, and I
> then have to fix them manually.

You need to create an empty ChangeLog file in the top source dir.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Date: Wed, 01 Dec 2021 00:56:27 +0100
> Cc: Stefan Kangas <stefan@marxist.se>, Emacs developers <emacs-devel@gnu.org>
> 
> On Nov 30 2021, Philipp Stephani wrote:
> 
> > That almost never does the right thing for me, though. It almost
> > always tries to create a ChangeLog file in a subdirectory (e.g.
> > "lisp") and makes the filenames relative to that subdirectory, and I
> > then have to fix them manually.
> 
> You need to create an empty ChangeLog file in the top source dir.

It works for me regardless.  If there's no ChangeLog file, it creates
a buffer with a suitable name, and puts the entry there, relative to
the top-level directory of the tree.

Re: File names in ChangeLog entries

[Stefan Monnier]

> I've had to spend quite some time fixing up ChangeLog entries in
> preparation of the Emacs 28 pretest, and as you can imagine this work is
> both manual and time consuming.

FWIW, I can't remember the last time I looked at a ChangeLog file.

OTOH, I would really appreciate if people could be careful to always
include some kind of file information on the first line of their commit.
Too often I see commits whose first line doesn't unambiguously indicate
which part of Emacs's code is changed.


        Stefan

Re: File names in ChangeLog entries

[Stefan Kangas]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> FWIW, I can't remember the last time I looked at a ChangeLog file.

Indeed, I also never look at them.

> OTOH, I would really appreciate if people could be careful to always
> include some kind of file information on the first line of their commit.
> Too often I see commits whose first line doesn't unambiguously indicate
> which part of Emacs's code is changed.

In the past I often used the format

    Fix foo in image-dired.el

Recently, I've made some changes to image-dired.el where I instead used
the format

    image-dired: Fix foo

I quite like this format, as it is both easy to read and immediately
obvious what it's about.

Maybe it would make sense to start encouraging some more standardized
format for the first line of commit messages?  This seems like something
that was probably discussed in the past (before I was following
emacs-devel), so apologies in advance if I'm just beating a dead horse.

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 30 Nov 2021 15:55:17 -0800
> Cc: emacs-devel@gnu.org
> 
> Maybe it would make sense to start encouraging some more standardized
> format for the first line of commit messages?

If you can come up with a format that can be reliably used in all
cases, yes.  But I very much doubt you'd be able to do that.  The
first line is just one line, and it must be short enough.  It is easy
to write something short there, but not if the description is
complicated.

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Tue, 30 Nov 2021 18:16:36 -0500
> 
> OTOH, I would really appreciate if people could be careful to always
> include some kind of file information on the first line of their commit.
> Too often I see commits whose first line doesn't unambiguously indicate
> which part of Emacs's code is changed.

Please also make a point of following the conventions of ChangeLog
entries.  You (Stefan) are one of the "worst offenders" in that
department: your entries look very frequently backwards: first the
file and function, then an empty line, then the detailed explanation
of the change.  It should be the other way around (if you care about
the quality of the logs).

Re: File names in ChangeLog entries

[Stefan Monnier]

> entries.  You (Stefan) are one of the "worst offenders" in that
> department: your entries look very frequently backwards: first the
> file and function, then an empty line, then the detailed explanation
> of the change.  It should be the other way around (if you care about
> the quality of the logs).

Mmmhh... maybe there's a misunderstanding then.
I thought the agreed upon format is:

    * filenames: Short description

    Explanation.

    * file1 (func1): desc1.
    (func2): desc2.
    * file2 (func3): desc3.

Which can degenerate to:

    * filename (func): Short description

    Explanation or rest of the description.

when the change only touches a single function.
And I also use

    * file1: Short description

    Explanation.

    (func1): desc1.
    (func2): desc2.
    * file2 (func3): desc3.

when the change fundamentally only affects `file1` except for minor
adjustments in a few other files.

I'm not completely sure about the use of the `* ` at the beginning of
the first line, which is not very useful but I keep out of habit.


        Stefan

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: stefan@marxist.se,  emacs-devel@gnu.org
> Date: Wed, 01 Dec 2021 08:39:06 -0500
> 
> Which can degenerate to:
> 
>     * filename (func): Short description
> 
>     Explanation or rest of the description.

Please don't degenerate like that.

Re: File names in ChangeLog entries

[Stefan Monnier]

Eli Zaretskii [2021-12-01 15:52:08] wrote:
>> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> Cc: stefan@marxist.se,  emacs-devel@gnu.org
>> Date: Wed, 01 Dec 2021 08:39:06 -0500
>> 
>> Which can degenerate to:
>> 
>>     * filename (func): Short description
>> 
>>     Explanation or rest of the description.
>
> Please don't degenerate like that.

You want

    * filename (func): Short description

    * filename (func): description.

instead?

What about

    * filename (func): Short description

    Explanation

should I rewrite it to:

    * filename (func): Short description

    Explanation

    * filename (func): Short description.

?


        Stefan

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: stefan@marxist.se,  emacs-devel@gnu.org
> Date: Wed, 01 Dec 2021 11:51:56 -0500
> 
> Eli Zaretskii [2021-12-01 15:52:08] wrote:
> >> From: Stefan Monnier <monnier@iro.umontreal.ca>
> >> Cc: stefan@marxist.se,  emacs-devel@gnu.org
> >> Date: Wed, 01 Dec 2021 08:39:06 -0500
> >> 
> >> Which can degenerate to:
> >> 
> >>     * filename (func): Short description
> >> 
> >>     Explanation or rest of the description.
> >
> > Please don't degenerate like that.
> 
> You want
> 
>     * filename (func): Short description
> 
>     * filename (func): description.
> 
> instead?

No, I want the standard:

  Summary description

  * file1 (func1): Description of change in func1.

  * file2 (func2): Description of change in func2.

> What about
> 
>     * filename (func): Short description
> 
>     Explanation
> 
> should I rewrite it to:
> 
>     * filename (func): Short description
> 
>     Explanation
> 
>     * filename (func): Short description.
> 
> ?

No.  I don't understand why you insist on putting the file/function
part on the first (a.k.a. "header") line.  The header line is supposed
to be a summary, so that the likes of

  git log --pretty='format:%h %cd %an %s'

work as expected.

Re: File names in ChangeLog entries

[Karl Fogel]

>No.  I don't understand why you insist on putting the 
>file/function
>part on the first (a.k.a. "header") line.  The header line is 
>supposed
>to be a summary, so that the likes of
>
>  git log --pretty='format:%h %cd %an %s'
>
>work as expected.

This is all documented in CONTRIBUTE, by the way.

If someone wants to argue that we should change the standard, 
that's a different conversation.  I'm just saying (and I think 
this might be partly what Eli is saying too) that there *is* 
currently a standard and there's no ambiguity about what that 
standard is.

Best regards,
-Karl

Re: File names in ChangeLog entries

[Stefan Monnier]

>>     * filename (func): Short description
>> 
>>     Explanation
>> 
>>     * filename (func): Short description.
>> 
>> ?
>
> No.  I don't understand why you insist on putting the file/function
> part on the first (a.k.a. "header") line.  The header line is supposed
> to be a summary, so that the likes of

The first line summary should also summarize the files.

The Linux kernel uses the same principle where the first line starts
with a description of the "subsystem" that's affected.

That goes back to my original message in this thread: I regularly see
commit messages where the first line is only complete if you know to
which (set of) file(s) the change is applied.

E.g.:

    Avoid unnecessary call when pixel scrolling

Maybe this is a change in the `pixel-scroll` package, but it could also
be a change in some completely different package which happens to fix
a problem that occurs when used in conjunction with pixel scrolling.


        Stefan

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: stefan@marxist.se,  emacs-devel@gnu.org
> Date: Wed, 01 Dec 2021 13:46:52 -0500
> 
> >>     * filename (func): Short description
> >> 
> >>     Explanation
> >> 
> >>     * filename (func): Short description.
> >> 
> >> ?
> >
> > No.  I don't understand why you insist on putting the file/function
> > part on the first (a.k.a. "header") line.  The header line is supposed
> > to be a summary, so that the likes of
> 
> The first line summary should also summarize the files.

No, it doesn't need to do that.  And it frequently isn't even
possible.  In any case, this is not our conventions (they are also not
what the GCS say).

> That goes back to my original message in this thread: I regularly see
> commit messages where the first line is only complete if you know to
> which (set of) file(s) the change is applied.
> 
> E.g.:
> 
>     Avoid unnecessary call when pixel scrolling
> 
> Maybe this is a change in the `pixel-scroll` package, but it could also
> be a change in some completely different package which happens to fix
> a problem that occurs when used in conjunction with pixel scrolling.

Yes, we have some not very good summaries.  But I'm sure you will have
no difficulties in writing good summary lines.

Once again, the format we ask for is:

  Summary line

  Detailed description of the change, the reasons for it, and any
  other relevant information (if any).
  * file (func): Description of the change in file:func.

Re: File names in ChangeLog entries

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 2466 bytes --]


[recip list trimmed]

() Stefan Monnier <monnier@iro.umontreal.ca>
() Wed, 01 Dec 2021 13:46:52 -0500

   The Linux kernel uses the same principle where the first line
   starts with a description of the "subsystem" that's affected.

Personally, in the ChangeLog entries i generate (for other
projects, not for Emacs), i generalize this principle.  I.e.,
whereas Linux uses:

 SUBSYSTEM: SHORT-DESCRIPTION

i use instead:

 [SUBSYSTEM OTHER-ATTR] SHORT-DESCRIPTION

That OTHER-ATTR is often something like ‘C’ (for C code or
libraries, as opposed to Scheme, for exapmle), or ‘int’ (for
"internal" as opposed to user-visible).  Example:

 https://git.savannah.gnu.org/cgit/rcs.git/tree/ChangeLog

In any case, the practice makes it easy to filter and sort
changes (for those who like to ponder Change :-D).

   That goes back to my original message in this thread: I
   regularly see commit messages where the first line is only
   complete if you know to which (set of) file(s) the change is
   applied.

   E.g.:

       Avoid unnecessary call when pixel scrolling

   Maybe this is a change in the `pixel-scroll` package, but it
   could also be a change in some completely different package
   which happens to fix a problem that occurs when used in
   conjunction with pixel scrolling.

I suppose under the Linux practice, this could be:

 pixel-scroll: Avoid unnecesary call when scrolling

and under mine:

 [pixel-scroll int] Avoid unnecesary call when scrolling

Note that, because SUBSYSTEM establishes the context, there is
no need to include the "pixel" qualifier in SHORT-DESCRIPTION.
I am guessing about ‘int’ because the change seems to be
performance (efficiency) related and not user-visible.

BTW, in the past i always punctuated (placed a period at the end
of SHORT-DESCRIPTION), but i've come around to the mindset of
punctuationlessness of late.

I suggest we choose one of these methods and add it explicitly
to CONTRIBUTE.  I see the "; SUMMARY" syntax is documented, why
not this, as well?

-- 
Thien-Thi Nguyen -----------------------------------------------
 (defun responsep (query)               ; (2021) Software Libero
   (pcase (context query)               ;       = Dissenso Etico
     (`(technical ,ml) (correctp ml))
     ...))                              748E A0E8 1CB8 A748 9BFA
--------------------------------------- 6CE4 6703 2224 4C80 7502


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 219 bytes --]

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Thien-Thi Nguyen <ttn@gnuvola.org>
> Date: Wed, 01 Dec 2021 14:22:51 -0500
> Cc: emacs-devel@gnu.org
> 
> I suggest we choose one of these methods and add it explicitly
> to CONTRIBUTE.  I see the "; SUMMARY" syntax is documented, why
> not this, as well?

Because the problem is not with what CONTRIBUTE says, the problem is
that Stefan and others don't WANT to do what it says.  How will it
help to make the requirements more complex and harder to follow if we
are unable to ensure people follow the simpler ones we have now, and
even veteran contributors and native English speakers such as Stefan
oppose what we say there (which is really the same as what
standards.texi says, just shorter)?

Re: File names in ChangeLog entries

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 1621 bytes --]


[cc trimmed]

() Eli Zaretskii <eliz@gnu.org>
() Wed, 01 Dec 2021 21:32:42 +0200

   Because the problem is not with what CONTRIBUTE says, the
   problem is that Stefan and others don't WANT to do what it
   says.  How will it help to make the requirements more complex
   and harder to follow if we are unable to ensure people follow
   the simpler ones we have now, and even veteran contributors
   and native English speakers such as Stefan oppose what we say
   there (which is really the same as what standards.texi says,
   just shorter)?

Enforcement is always an issue.

My point is that if policy is (clearly) written down, that makes
everything else (including enforcement) easier.  I pointed out a
shared value (i.e., including "subsystem" info in the summary)
in the objections voiced by Stefan that i hope we (collectively,
all of us) can agree on.  In this way, perhaps there is a way
forward to avoid future conflict.

Actually, characterizing those statements as objections is not
entirely correct, either... perhaps it's better to say they were
explanations of his confusion.  In which case, my proposal has
even more hope of success (fingers crossed), i think...

Anyway, back to lurking.  :-D

-- 
Thien-Thi Nguyen -----------------------------------------------
 (defun responsep (query)               ; (2021) Software Libero
   (pcase (context query)               ;       = Dissenso Etico
     (`(technical ,ml) (correctp ml))
     ...))                              748E A0E8 1CB8 A748 9BFA
--------------------------------------- 6CE4 6703 2224 4C80 7502


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 219 bytes --]

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Thien-Thi Nguyen <ttn@gnuvola.org>
> Cc: emacs-devel@gnu.org
> Date: Wed, 01 Dec 2021 15:49:15 -0500
> 
> My point is that if policy is (clearly) written down, that makes
> everything else (including enforcement) easier.  I pointed out a
> shared value (i.e., including "subsystem" info in the summary)
> in the objections voiced by Stefan that i hope we (collectively,
> all of us) can agree on.  In this way, perhaps there is a way
> forward to avoid future conflict.

Including a subsystem in the summary line leaves less space for the
actual content, and that space is already at premium.  AFAIU, the
temptation to break the "standard" format is to some degree explained
by the fact that many "* file (func): Desc" descriptions are _almost_
short enough to act as their own summary line; your proposal will
disallow more of those, due to the need to state the subsystem there.

So it doesn't sound to me as an improvement, in general.

Thanks.

Re: File names in ChangeLog entries

[Stefan Monnier]

>> The first line summary should also summarize the files.
> No, it doesn't need to do that.

I think it should.

> And it frequently isn't even possible.

That sounds very odd.  Can you give examples?

> In any case, this is not our conventions (they are also not what the
> GCS say).

Conventions can be changed.  That's why I brought up this issue in the
first place.  I did mention this the last time we discussed the
conventions, but apparently it was either overlooked or ignored, whereas
I thought it was obviously accepted as not even needing discussion.

And indeed, I'm surprised it's controversial ;-)

> Because the problem is not with what CONTRIBUTE says, the problem is
> that Stefan and others don't WANT to do what it says.

For the record the problem for me is the following: I read the
`emacs-diffs` mailing-list but I don't read all the messages.  I filter
them based on the Subject, and having some idea of which part of the
code is affected is a crucial information for me to decide whether
I should look at the patch.

I can live with using

    * filename (func): Short description

    Explanation

and

    * filename (func): Short description

    Explanation

    * filename (func): Short description.

if that's what it takes to abide by the official conventions while at the
same time satisfy my own desire to help other people like me who need to
decide what is affected by a given patch by just reading the summary.

But I really wish we could change the convention so that I don't need to
suffer because other people don't include that info in their summary line.


        Stefan

Re: File names in ChangeLog entries

[Stefan Kangas]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> I can live with using
>
>     * filename (func): Short description
>
>     Explanation

Why do you want "* ", " (func)" and "." on the summary line?  To my
mind, that just makes the line longer.

> But I really wish we could change the convention so that I don't need to
> suffer because other people don't include that info in their summary line.

Whatever we do, I hope we can avoid including ChangeLog-style characters
in the preferred summary line format.

Personally, I think we should just make the summary line mandatory even
when the ChangeLog entry fits on one line.  It makes for easier reading
of "git log --format=short" and similar.  But that's me.

Re: File names in ChangeLog entries

[Stefan Monnier]

>> I can live with using
>>
>>     * filename (func): Short description
>>
>>     Explanation
>
> Why do you want "* ", " (func)" and "." on the summary line?  To my
> mind, that just makes the line longer.

I don't need the "* " there (as mentioned earlier I just usually put it
there out of habit).  Not sure what you mean by "." since there's no such char in my sample
above, AFAICT.
As for the " (func)" I only put it there if there's room.
Otherwise I use the longer form:

    * filenames: Short description

    Explanation.

    * file1 (func1): desc1.
    (func2): desc2.
    * file2 (func3): desc3.

where "filenames" is a summary of the files.  I don't have a precise
rule for what this should look like because creativity is sometimes
needed to make the whole thing fit on a single line.


        Stefan

Re: File names in ChangeLog entries

[Stefan Kangas]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> As for the " (func)" I only put it there if there's room.

In cases where mentioning the function is particularly important, I'd
rather say

    function-name: Short description

Given that we prefer to include package prefixes in our symbols, it
should also tell you something about where the function can be found.
In many cases, at least.

But as you say, it is hard to find hard rules, and some creativity will
inevitably be needed.

Re: File names in ChangeLog entries

[Karl Fogel]

[-- Attachment #1: Type: text/plain, Size: 2160 bytes --]

On 01 Dec 2021, Stefan Kangas wrote:
>Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>> As for the " (func)" I only put it there if there's room.
>
>In cases where mentioning the function is particularly important, 
>I'd
>rather say
>
>    function-name: Short description
>
>Given that we prefer to include package prefixes in our symbols, 
>it
>should also tell you something about where the function can be 
>found.
>In many cases, at least.
>
>But as you say, it is hard to find hard rules, and some 
>creativity will
>inevitably be needed.

The main point, though, is the one you yourself made earlier:

There is a good reason to keep that first summary line as short as 
possible.  Git often prints it prefixed by other information, in 
such a way that the summary line gets crammed against the right 
edge -- so if it's too long, it may wrap awkwardly or go off the 
screen.

You gave "git log --format=short" as an example, but an even more 
common situation in my experience is "git show-branch".  I'll 
attach some output from that command to this email (as an actual 
text/plain attachment, to make absolutely sure the formatting is 
preserved, since the formatting is important here).  If one looks 
at that output, one can see right away why having reliably short 
summary first-lines in the commit messages is useful.

Many free software projects have adopted a "50 characters, with no 
trailing dot" rule for that first line, to the point where 
programmers often treat it as a standard.  (When we onboard new 
programmers at our company, for example, I find that they 
generally already know about this rule and expect us to be 
following it, which we are.)  Emacs doesn't have to do things the 
way those other projects do, but I hope the above helps clarify 
why we might want to be more consistent about doing it that way.

Our CONTRIBUTE file does already say that 50 chars for the summary 
line is "nicer".  (Although it gives that advice two points down 
from where we first mention the summary line, which is odd.  I've 
attached a patch here that tries to improve this, and would 
appreciate others' review.)

Best regards,
-Karl


[-- Attachment #2: 'git show-branch' sample output --]
[-- Type: text/plain, Size: 987 bytes --]

$ git show-branch master emacs-28
* [master] * lisp/cedet/semantic/bovine/c.el (semantic-tag-protection): Silence warning
 ! [emacs-28] ; Update loaddefs files.
--
*  [master] * lisp/cedet/semantic/bovine/c.el (semantic-tag-protection): Silence warning
*  [master^] * lisp/emacs-lisp/macroexp.el: Improve last change
*  [master~2] Add some primitive momentum-based precision scrolling
*  [master~3] Add `touch-end' event type
*  [master~37] Add an ldefs-boot.el target to the Makefile
...
*  [master~1208] Save position in mark ring before jumping to definition
*  [master~1209] Update emacs-module sources for Emacs 29
*  [master~1210] Bump Emacs version to 29.0.50
 + [emacs-28] ; Update loaddefs files.
 + [emacs-28^] ; make change-history-commit
 + [emacs-28~2] * lisp/repeat.el: Use same logic for repeat-check-key and repeat-exit-timeout.
...
 + [emacs-28~11] CC Mode: Recognise "struct foo {" as introducing a type declaration
*+ [emacs-28~12] ; Auto-commit of loaddefs files.
$ 

[-- Attachment #3: PATCH: Improve CONTRIBUTE's documentation of commit messages --]
[-- Type: text/plain, Size: 2038 bytes --]

diff --git CONTRIBUTE CONTRIBUTE
index 5740004637..7c3421ed75 100644
--- CONTRIBUTE
+++ CONTRIBUTE
@@ -185,20 +185,26 @@ ChangeLog file, where they can be corrected.  It saves time to get
 them right the first time, so here are guidelines for formatting them:
 
 - Start with a single unindented summary line explaining the change;
-  do not end this line with a period.  If that 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.
+  do not end this line with a period.  If possible, try to keep the
+  summary line to 50 characters or fewer; this is for compatibility
+  with certain Git commands that print that line in width-constrained
+  contexts.
 
-- After the summary line, there should be an empty line, then
-  unindented ChangeLog entries.
+  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.
+
+- After the summary line, there should be an empty line.
+
+- 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.
 
 - Limit lines in commit messages to 78 characters, unless they consist
   of a single word of at most 140 characters; this is enforced by a
-  commit hook.  It's nicer to limit the summary line to 50 characters;
-  this isn't enforced.  If the change can't be summarized so briefly,
-  add a paragraph after the empty line and before the individual file
-  descriptions.
+  commit hook.
 
 - If only a single file is changed, the summary line can be the normal
   file first line (starting with the asterisk).  Then there is no

Re: File names in ChangeLog entries

[Stefan Monnier]

> There is a good reason to keep that first summary line as short as possible.
[...]
> Many free software projects have adopted a "50 characters, with no trailing
> dot" rule for that first line, to the point where programmers often treat it

50 chars seems enough to include some "subsystem" information, so
I think our two proposals are compatible.


        Stefan

Re: File names in ChangeLog entries

[Juri Linkov]

> *  [master~1208] Save position in mark ring before jumping to definition

This is a good example of an unhelpful commit message.
There is no way to guess it's about lisp/help-mode.el.

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: Stefan Kangas <stefan@marxist.se>,  Eli Zaretskii <eliz@gnu.org>,
>   emacs-devel@gnu.org,  Stefan Monnier <monnier@iro.umontreal.ca>,
>   Thien-Thi Nguyen <ttn@gnuvola.org>
> Date: Thu, 02 Dec 2021 11:12:05 +0200
> 
> > *  [master~1208] Save position in mark ring before jumping to definition
> 
> This is a good example of an unhelpful commit message.
> There is no way to guess it's about lisp/help-mode.el.

You don't need to guess, you need to look at the rest of the log
message.  We cannot realistically require that everything about the
change will be clear from the summary.  Mentioning file names is, IME,
mostly a waste there, because the file name provides very little
information about the change itself, and takes quite a lot of space,
so doesn't allow to say enough about the change.

Re: File names in ChangeLog entries

[Stefan Monnier]

>> > *  [master~1208] Save position in mark ring before jumping to definition
>> This is a good example of an unhelpful commit message.
>> There is no way to guess it's about lisp/help-mode.el.
> You don't need to guess, you need to look at the rest of the log
> message.

I guess that begs the question: what do you think is the role of the
Summary, IOW how is it intended/expected to be used?

In my own experience, there are two main cases where I've made use of them:

- When listing a chain of commits for a particular change.
  Usually the "particular change" already makes it clear which parts of
  the code will likely be affected, so having subsystem information
  there is not super important, admittedly.
  Instead, I read the summaries as a kind of "roadmap" for how the
  change is decomposed into a number of steps.
  Since we're usually talking about a handful of commits, the specific
  shape and content of those summaries doesn't matter very much (they
  just need to include enough info that I know which commit is which).

- When listing a number of commits that were applied to a branch like
  `master` or `emacs-28`, typically for code review, but other times to
  look for changes relevant to some problem I'm experiencing or some
  specific code I'm playing with.
  In that case, having subsystem information in the summary makes
  a world of difference in that I can much more easily skip changes
  which are "obviously" irrelevant.

I wonder how you use them.


        Stefan

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Juri Linkov <juri@linkov.net>,  kfogel@red-bean.com,  stefan@marxist.se,
>   emacs-devel@gnu.org,  ttn@gnuvola.org
> Date: Thu, 02 Dec 2021 16:09:20 -0500
> 
> > You don't need to guess, you need to look at the rest of the log
> > message.
> 
> I guess that begs the question: what do you think is the role of the
> Summary, IOW how is it intended/expected to be used?
> 
> In my own experience, there are two main cases where I've made use of them:
> 
> - When listing a chain of commits for a particular change.

I don't understand what this means.  Are you talking about the history
of changes in a particular region of a file?  Then "git log -L" is
your friend.

> I wonder how you use them.

I just read the summary and find the ones that could potentially be
relevant to whatever I'm looking for.  But mostly I just use "git log",
where I see the entire log message with all the details.

Re: File names in ChangeLog entries

[Stefan Monnier]

>> - When listing a chain of commits for a particular change.
> I don't understand what this means.  Are you talking about the history
> of changes in a particular region of a file?  Then "git log -L" is
> your friend.

No, I'm thinking more of

    git log --pretty=short master..FEATUREBRANCH

or what I get during `git rebase`.


        Stefan

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: juri@linkov.net,  kfogel@red-bean.com,  stefan@marxist.se,
>   emacs-devel@gnu.org,  ttn@gnuvola.org
> Date: Fri, 03 Dec 2021 07:57:19 -0500
> 
> >> - When listing a chain of commits for a particular change.
> > I don't understand what this means.  Are you talking about the history
> > of changes in a particular region of a file?  Then "git log -L" is
> > your friend.
> 
> No, I'm thinking more of
> 
>     git log --pretty=short master..FEATUREBRANCH
> 
> or what I get during `git rebase`.

I use "git diff" for reviewing branches.  "git log" is insufficient
because people who work on a branch rarely if ever bother to make
useful log messages.

Re: File names in ChangeLog entries

[Karl Fogel]

On 02 Dec 2021, Eli Zaretskii wrote:
>> From: Juri Linkov <juri@linkov.net>
>> Cc: Stefan Kangas <stefan@marxist.se>,  Eli Zaretskii 
>> <eliz@gnu.org>,
>>   emacs-devel@gnu.org,  Stefan Monnier 
>>   <monnier@iro.umontreal.ca>,
>>   Thien-Thi Nguyen <ttn@gnuvola.org>
>> Date: Thu, 02 Dec 2021 11:12:05 +0200
>> 
>> > *  [master~1208] Save position in mark ring before jumping to 
>> > definition
>> 
>> This is a good example of an unhelpful commit message.
>> There is no way to guess it's about lisp/help-mode.el.
>
>You don't need to guess, you need to look at the rest of the log
>message.  We cannot realistically require that everything about 
>the
>change will be clear from the summary.  Mentioning file names is, 
>IME,
>mostly a waste there, because the file name provides very little
>information about the change itself, and takes quite a lot of 
>space,
>so doesn't allow to say enough about the change.

Agreed.

The point of the summary line is to encapsulate some recognizable 
core thing about the change.  When you're reading over, say, a 
long vertical list of such summaries, you can quickly recognize 
ones you already had some awareness of (and this makes branch 
comparison much easier).

We'll never be able to fit *everything* in a summary line, and 
there's no need to.  If one needs further information about that 
particular change, one can go look at the full message.

Best regards,
-Karl

Re: File names in ChangeLog entries

[Stefan Kangas]

Karl Fogel <kfogel@red-bean.com> writes:

> Our CONTRIBUTE file does already say that 50 chars for the summary
> line is "nicer".  (Although it gives that advice two points down
> from where we first mention the summary line, which is odd.  I've
> attached a patch here that tries to improve this, and would
> appreciate others' review.)

LGTM.

Re: File names in ChangeLog entries

[Karl Fogel]

On 02 Dec 2021, Stefan Kangas wrote:
>Karl Fogel <kfogel@red-bean.com> writes:
>
>> Our CONTRIBUTE file does already say that 50 chars for the 
>> summary
>> line is "nicer".  (Although it gives that advice two points 
>> down
>> from where we first mention the summary line, which is odd. 
>> I've
>> attached a patch here that tries to improve this, and would
>> appreciate others' review.)
>
>LGTM.

Commit f35d6a9c732e (on emacs-28).  Thanks for the review, Stefan.

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Eli Zaretskii <eliz@gnu.org>,  Thien-Thi Nguyen <ttn@gnuvola.org>,
>   emacs-devel@gnu.org
> Date: Wed, 01 Dec 2021 17:21:57 -0500
> 
>     * filenames: Short description
> 
>     Explanation.
> 
>     * file1 (func1): desc1.
>     (func2): desc2.
>     * file2 (func3): desc3.
> 
> where "filenames" is a summary of the files.

This is okay, and doesn't violate our conventions.  (It does waste
precious space on the summary line to mention the file names, which
IME isn't necessary when the summary is well written.  But that's me.)
My problem is not with the above format, my problem is with log
messages that don't really follow it.  Like this one:

    * test/src/comp-tests.el: Rework last patch

    Move `require`s out of `eval-when-compile` if the functions are called
    at run-time.
    Don't use #' to quote symbols (i.e. at those places where a lambda
    expression couldn't be used).
    Don't pre-load comp-test-45603.el and comp-test-pure.el any more.

    (comp-deftest pure): Use `declare-function` after loading `comp-test-pure.el`
    to silence the byte-compiler.

This doesn't state the file name after the summary.  (Also, the lines
are too long, and will produce ugly ChangeLog entries in the tarball.)

    * lisp/emacs-lisp/subr-x.el (with-memoization): New macro

    Extracted from `cl-generic.el`.

    * lisp/emacs-lisp/cl-generic.el (cl--generic-get-dispatcher)
    (cl--generic-build-combined-method, cl-generic-generalizers): Use it.
    (cl--generic-with-memoization): Delete.

This doesn't mention subr-x.el change in the "main part".

    Change ruby-align-chained-calls indendation

    * lisp/progmodes/ruby-mode.el (ruby-smie-rules): Align with the
    first sibling on the previous line instead of the last (bug#32496).

    That is, before it used to be

    one.two.three
           .four

    and now it is

    one.two.three
       .four

Here, the order is incorrect: the "That is" part should have been
before the "* file (func): Desc" part, not after.

All in all, it looks like you arbitrarily put one of the log entries
on the first line to save repetition.  But some of the repetition is
due to your self-imposed conventions: there's no need to state the
full file name, with leading directories, on the summary line.  For
example, this summary:

    * lisp/emacs-lisp/subr-x.el (with-memoization): New macro

could have been more economically written as

    New macro 'with-memoization'

or, if you insist on mentioning the file, as

    New macro 'with-memoization' in subr-x.el

And in this example:

    * lisp/emacs-lisp/cl-generic.el: Try and fix bug#49866

    (cl-generic-generalizers): Remember the specializers that match
    a given value.
    (cl--generic-eql-generalizer): Adjust accordingly.

    * test/lisp/emacs-lisp/cl-generic-tests.el (cl-generic-test-01-eql):
    Add corresponding test.

the file name in the summary is entirely redundant, since fixing a bug
is not necessarily related to a particular file (as the rest of the
log message clearly shows).

And the main problem with your format is that the produced ChangeLog
is ugly and hard to read, while the format we prefer is carefully
designed to produce reasonably-readable ChangeLogs.  Which was why
Stefan Kangas started this discussion in the first place, AFAIU.

I hope this clarifies why I'm unhappy with your log messages.  And if
this is still not convincing, I don't intend to keep arguing, because
I have very little faith that it will lead anywhere useful.  I just
share the frustration expressed by Stefan Kangas (which in his case
came after he invested a lot of efforts fixing that).

Re: File names in ChangeLog entries

[Stefan Monnier]

>     * test/src/comp-tests.el: Rework last patch
>
>     Move `require`s out of `eval-when-compile` if the functions are called
>     at run-time.
>     Don't use #' to quote symbols (i.e. at those places where a lambda
>     expression couldn't be used).
>     Don't pre-load comp-test-45603.el and comp-test-pure.el any more.
>
>     (comp-deftest pure): Use `declare-function` after loading `comp-test-pure.el`
>     to silence the byte-compiler.
>
> This doesn't state the file name after the summary.  (Also, the lines
> are too long, and will produce ugly ChangeLog entries in the tarball.)

Indeed, it seems redundant to mention the file name afterwards since
it's the only file affected and it's already mentioned in the summary.
But I'm fine with adding the repetition here.

>     * lisp/emacs-lisp/subr-x.el (with-memoization): New macro
>
>     Extracted from `cl-generic.el`.
>
>     * lisp/emacs-lisp/cl-generic.el (cl--generic-get-dispatcher)
>     (cl--generic-build-combined-method, cl-generic-generalizers): Use it.
>     (cl--generic-with-memoization): Delete.
>
> This doesn't mention subr-x.el change in the "main part".

Yes, this is a hybrid between the old

    * lisp/emacs-lisp/subr-x.el (with-memoization): New macro
    Extracted from `cl-generic.el`.
    
    * lisp/emacs-lisp/cl-generic.el (cl--generic-get-dispatcher)
    (cl--generic-build-combined-method, cl-generic-generalizers): Use it.
    (cl--generic-with-memoization): Delete.

and the new summary+explanation+changelog format where I tried to be
clever since the `subr-x` part is the core one and the other ones are
just minor sidekicks.
I'm fine with avoiding such cleverness.

>     Change ruby-align-chained-calls indendation
>
>     * lisp/progmodes/ruby-mode.el (ruby-smie-rules): Align with the
>     first sibling on the previous line instead of the last (bug#32496).
>
>     That is, before it used to be
>
>     one.two.three
>            .four
>
>     and now it is
>
>     one.two.three
>        .four
>
> Here, the order is incorrect: the "That is" part should have been
> before the "* file (func): Desc" part, not after.

Not sure what I was smoking back then, indeed.

> due to your self-imposed conventions: there's no need to state the
> full file name, with leading directories, on the summary line.

Agreed.  I just need/want *some* information about which files
are affected.  `ruby-mode` or `subr-x` would be perfectly fine for that.

> For
> example, this summary:
>
>     * lisp/emacs-lisp/subr-x.el (with-memoization): New macro
>
> could have been more economically written as
>
>     New macro 'with-memoization'
>
> or, if you insist on mentioning the file, as
>
>     New macro 'with-memoization' in subr-x.el

I'd prefer

     subr-x (with-memoization): New macro

which is closer to the rest of our conventions.  Having the subsystem
info always at the beginning is important to be able to visually scan
many commits quickly without having to read&parse&understand each and
every summary text.  It's even more important when several commits in
a row affect the same subsystem in which case the scanning is made even
faster when all those commits put the subsystem info at the same place.

> And in this example:
>
>     * lisp/emacs-lisp/cl-generic.el: Try and fix bug#49866
>
>     (cl-generic-generalizers): Remember the specializers that match
>     a given value.
>     (cl--generic-eql-generalizer): Adjust accordingly.
>
>     * test/lisp/emacs-lisp/cl-generic-tests.el (cl-generic-test-01-eql):
>     Add corresponding test.
>
> the file name in the summary is entirely redundant, since fixing a bug
> is not necessarily related to a particular file (as the rest of the
> log message clearly shows).

I don't understand what you mean: the patch basically only touches
`cl-generic.el`.

> And the main problem with your format is that the produced ChangeLog
> is ugly and hard to read, while the format we prefer is carefully
> designed to produce reasonably-readable ChangeLogs.  Which was why
> Stefan Kangas started this discussion in the first place, AFAIU.

Indeed, this discussion is related to the generation of the ChangeLog
and to the fact that I have completely and totally stopped looking at
them, so I'm beginning to doubt the usefulness of
keeping/generating them.  [ I'm curious to know who uses them still.  ]

But I can accommodate a convention where the file names are always
clearly spelled out in the "bottom changelog section", even if that's
redundant with the info in the summary line, for the benefit of
generating those legacy files.

Is there a chance that others might be willing to accommodate my request
to always include some subsystem info in the summary line in return?


        Stefan

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: stefan@marxist.se,  ttn@gnuvola.org,  emacs-devel@gnu.org
> Date: Thu, 02 Dec 2021 02:34:32 -0500
> 
> > For
> > example, this summary:
> >
> >     * lisp/emacs-lisp/subr-x.el (with-memoization): New macro
> >
> > could have been more economically written as
> >
> >     New macro 'with-memoization'
> >
> > or, if you insist on mentioning the file, as
> >
> >     New macro 'with-memoization' in subr-x.el
> 
> I'd prefer
> 
>      subr-x (with-memoization): New macro
> 
> which is closer to the rest of our conventions.

Our conventions are for the detailed descriptions of the changes.  the
summary line is supposed to be human-readable free text, not
machine-readable text in rigid format.  What you prefer is not bad,
but it is less readable by humans, IMO.

> Having the subsystem
> info always at the beginning is important to be able to visually scan
> many commits quickly without having to read&parse&understand each and
> every summary text.  It's even more important when several commits in
> a row affect the same subsystem in which case the scanning is made even
> faster when all those commits put the subsystem info at the same place.

Those are your personal goals, due to your particular usage of these
parts of the log messages.  But that's not the only use of them, and
not even the main one.

> > And in this example:
> >
> >     * lisp/emacs-lisp/cl-generic.el: Try and fix bug#49866
> >
> >     (cl-generic-generalizers): Remember the specializers that match
> >     a given value.
> >     (cl--generic-eql-generalizer): Adjust accordingly.
> >
> >     * test/lisp/emacs-lisp/cl-generic-tests.el (cl-generic-test-01-eql):
> >     Add corresponding test.
> >
> > the file name in the summary is entirely redundant, since fixing a bug
> > is not necessarily related to a particular file (as the rest of the
> > log message clearly shows).
> 
> I don't understand what you mean: the patch basically only touches
> `cl-generic.el`.

No, it also changes the test suite.

> Indeed, this discussion is related to the generation of the ChangeLog
> and to the fact that I have completely and totally stopped looking at
> them, so I'm beginning to doubt the usefulness of
> keeping/generating them.  [ I'm curious to know who uses them still.  ]

We had this discussion.  There are enough people who want to have a
usable ChangeLog in several situations.  Therefore we decided to
generate them when a release is tarred.  Restarting this discussion
because the ChangeLog format is not to the liking of some of us sounds
to me like a salami tactics: first we take Manhattan, then we take
Berlin.  Let's instead stick to our decisions.

> Is there a chance that others might be willing to accommodate my request
> to always include some subsystem info in the summary line in return?

I don't know.  For me, it'd be an annoyance: I usually try very hard
to come up with a short but detailed enough summary, which isn't easy
in some cases.  Having to "waste" some of the precious space on some
subsystem info would make this a lot harder.

Re: File names in ChangeLog entries

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Wed, 1 Dec 2021 13:50:23 -0800
> Cc: Thien-Thi Nguyen <ttn@gnuvola.org>, emacs-devel@gnu.org
> 
> Personally, I think we should just make the summary line mandatory even
> when the ChangeLog entry fits on one line.

That'd cause a lot of unnecessary repetition, so it will annoy people
even more.

Re: File names in ChangeLog entries

[Matt Armstrong]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> For the record the problem for me is the following: I read the
> `emacs-diffs` mailing-list but I don't read all the messages.  I
> filter them based on the Subject, and having some idea of which part
> of the code is affected is a crucial information for me to decide
> whether I should look at the patch.

Stefan, since your use case is reasonable, I wonder if there are
approaches not yet discussed that could satisfy it?

Point being, we're only discussing one possible approach to satisfying
your need, in a way that current guidance to change, asks people to
change habbits, and in a way that asks people to include arguably
redundant, but also largely mechanically defined, information in their
hand written commit messages.

So, two ideas:

A) Change CONTRIBUTE guidance slightly.

Today all we say is "Start with a single unindented summary line
explaining the change" but we don't describe what a good explanation is.
The current example is "Deactivate shifted region", which answers "what"
but not "where".  It could just as easily be "Deactivate region in newly
selected windows"

Point is not to satisfy the letter of what you're asking for, but to
suggest that the subject line should answer what the change is doing
and, if space available, where it applies.

B) Add tooling to generate a succinct "subsystem" description from a git
commit.

Case in point: the GNU ChangeLog format is bearable today because
tooling (partially) supports generating it.  Why not look at tooling for
this job too?

If we could come up with an algorithm that takes a git commit (staged or
already commited) and describes the "subsystem" (or subsystems) that are
touched, then:

 - we are forced to clearly describe what the "subsystem" description
   should look like (so far, "functions/files" is what Stefan's has aked
   for, but I suspect this guideline quickly breaks down for larger
   commits).

 - even if the commit message conventions remain the same, it becomes
   almost trivial to produce a log of succinct "[subsystem(s)]: [summary
   line]" descriptions,

   - and even concievable that the `emacs-diffs` list could use this in
     its subject lines.
   - ...or this subsystem description logic could be applied to commits
     in the past...

For what it is worth, I skimmed the most recent 100 or so emacs commit
messages and noticed two things:

 - I could already tell which "subsystem" was touched for most of the
   commits.

 - I thought that Lars' subject lines struck a nice balance (for me)
   between reading like English but also covering the questions of
   "what" and "where."

Re: File names in ChangeLog entries

[Alfred M. Szmidt]

   Do not use any of these formats:

       [not the full file name:]

	   * tetris.el: Foo.

This one is correct _if_ there would have been a ChangeLog file in
lisp/play.  If changing the heuristics of how things are figured out
this needs to be considered so that doesn't break.

       [not supported by our tools - patches welcome:]

	   * lisp/play/{tetris,morse}.el: Foo.

This is not a format that is encouraged by the GNU coding standards.
The reason is that it makes it impossible to search the file for
filenames.