bug#72341: VC: CVS template lines not stripped when committing

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 29 Jul 2024 11:53:13 +0200
> From: Christoph Badura <bad@bsd.de>
> Cc: 72341@debbugs.gnu.org
> 
> On Mon, Jul 29, 2024 at 05:26:50AM +0300, Eli Zaretskii wrote:
> > Somewhat clearer, thanks.  I don't see this stripping feature
> > documented in the CVS manual; did I miss something?
> 
> I didn't see it documented either.  The closest thing that comes to
> documentation of that feature is the documentation for rcsinfo:
> https://www.gnu.org/software/trans-coord/manual/cvs/html_node/rcsinfo.html#rcsinfo

This says nothing about the "CVS: " prefix, AFAICT.

> It is implemented in src/logmsg.c:do_editor().
> 
> > And one more questions: where do those "CVS:" lines come from when you
> > use the template file?
> 
> They have to be be in the template file.
> 
> I figure the idea is that the template files can contain "mandatory" text
> that will be part of the actuall log message and "explanatory" text,
> prefixed with "CVS: ", that will be stripped after the commit message has
> been edited.
> 
> As an example, here's the default template for the NetBSD repositories:
> ----------------8<------------------8<------------------8<-----------------
> CVS: ----------------------------------------------------------------------
> CVS: CVSROOT  cvs.NetBSD.org:/cvsroot
> CVS: please use "PR category/123" to have the commitmsg appended to PR 123
> ----------------8<------------------8<------------------8<-----------------
> 
> I'm only aware of the NetBSD and pkgsrc repositories that make use of CVS
> templates.  And their template files contain only lines prefixed with
> "CVS: ".

I think I see what's happening.  This is basically an undocumented
feature.  The removal of "CVS: " lines is there for when CVS itself
invokes the editor: in that case, it injects instructions into the
temporary file that it submits to the editor, and those instructions
all start with "CVS: ", so that they could be later removed.  IOW,
this prefix is basically an agreement between CVS and itself.

Now, nothing in the documentation of CVS/Template file says anything
about "CVS: ", but the code processes the temporary file, which
includes the template, the same as it processes the lines injected by
CVS, and thus every line that begins with "CVS: " in the template will
be removed.

IOW, NetBSD piggy-backs this feature to include their own instructions
in the template.

I'm unsure how to proceed with this.  My bother is that this is a
definite change in behavior wrt what VC did until now.  Users of VC
might be unaware of this removal, and could start some log lines with
the prefix, which will mysteriously disappear from the log message.

Dmitry, WDYT?  Maybe we should add this removal guarded by a user
option, by default off?  Or maybe we can identify where the template
starts and ends, and only remove in that region?

> Off topic and speaking of documentation.
> I noticed that
> https://www.gnu.org/software/emacs/manual/html_node/emacs/Log-Buffer.html
> doesn't document C-c C-k and doesn't explain how the region is set up so
> that an initial C-w will kill from point to the end of the buffer.  log-edit's
> documentation is also not correct with regard to this (i.e. the entire log
> buffer isn't emptied as point is after the Summary: header).
> 
> Is that worth reporting separately?

Yes, probably.  IMO, documenting "C-c C-k" should be accompanied with
the description of log-edit-comment-ring and its usage, otherwise the
command will not make sense to the users.