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."