Re: File names in ChangeLog entries

[Thien-Thi Nguyen]

[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

signature.asc
Description: PGP signature