Re: ChangeLog styles (was: master 7e387c9: * lisp/man.el (Man-width-max): New defcustom (bug#32536, bug#9385))

[Eli Zaretskii]

> From: Juri Linkov <address@hidden>
> Cc: address@hidden
> 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.