Subject: Re: bug#55039: [PATCH] Use VC-relative file names in ChangeLog entries

From: Eli Zaretskii <[email-masked]>
Date: Wed, 07 Sep 2022 16:27:17 +0300

> From: Philip Kaludercic <[email-masked]>
> Cc: Eli Zaretskii <[email-masked]>,  [email-masked]
> Date: Tue, 06 Sep 2022 20:10:41 +0000
> 
> --- a/doc/emacs/maintaining.texi
> +++ b/doc/emacs/maintaining.texi
> @@ -694,7 +694,10 @@ Log Buffer
>  (@code{log-edit-generate-changelog-from-diff}), to generate skeleton
>  ChangeLog entries, listing all changed file and function names based
>  on the diff of the VC fileset.  Consecutive entries left empty will be
> -combined by @kbd{C-q} (@code{fill-paragraph}).
> +combined by @kbd{C-q} (@code{fill-paragraph}).  By default the
> +inserted file names will just be the files without a path.  If
> +@code{diff-add-log-relative-names} is non-nil, a partial path relative
> +to the VC root directory will be inserted instead.

GNU Coding Standards frown on using "path" for anything but PATH-style
directory lists.  Please use "leading directories" or somesuch here,
as that's what you mean.

> +*** New user option 'diff-relative-names-in-changelog'.
> +If non-nil insert file names in ChangeLog skeletons relative to the
             ^
Comma missing there.

> +(defcustom diff-add-log-relative-names nil
> +  "Use relative file names when generating ChangeLog messages."

This doesn't say relative to what.  It also doesn't mention the
commands which are affected.

>  (defun diff-add-log-current-defuns ()
>    "Return an alist of defun names for the current diff.
>  The elements of the alist are of the form (FILE . (DEFUN...)),
> -where DEFUN... is a list of function names found in FILE."
> +where DEFUN... is a list of function names found in FILE.  If
> +`diff-add-log-relative-names' is non-nil, insert file names
> +relative to the VC root directory."

The "insert" part is out of place here, since there's no insertion.

How about

  If `diff-add-log-relative-names' is non-nil, file names in the alist
  are relative to the root directory of the VC repository.

instead?