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

[Christoph Badura]

On Mon, Jul 29, 2024 at 03:34:32PM +0300, Eli Zaretskii wrote:
> > 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.

That pretty much sums it up.

However, while this behaviour isn't mentioned in the documentation, it is
mentioned in every commit message file that cvs creates when it invokes an
editor.  E.g.:

CVS: ----------------------------------------------------------------------
CVS: Enter Log.  Lines beginning with `CVS:' are removed automatically
CVS: 
CVS: Committing in .
CVS: 
CVS: Modified Files:
CVS:    test.txt 
CVS: ----------------------------------------------------------------------

I have to admit, that after 30+ years of using cvs outside of emacs, my
brain filters out that bit of the commit message.  Anyway, it's clearly
advertised even if it isn't documented in the manual.

Note though, that when cvs invokes an editor itself to enter the commit
message, it is impossible to disable this behaviour.  That is, lines
starting with "CVS: " are always removed.

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

I've thought about that.  Clearly it is a change in behaviour.  The
interesting question is, will users notice?

My experience with this is that when I took up using emacs again after a
very long hiatus this behaviour of VC tripped me up on my first commit.
That was very annyoing indeed.  A friend suggested to M-x erase-buffer on
every commit.  Obviously he wasn't aware of that C-w would have the
desired effect.  Neither did I.  And that is not documented in the manual.

This was enough of a bother to not use VC again until this weekend and
then dig into why that is happending and not when I use "cvs ci file"
outside emacs (and have it invoke emacsclient).

If you work in an environment where other uses are using cvs outside of
emacs VC, the only way to have lines starting with "CVS: " in the stored
commit message is to require that the other users use "cvs ci -m" or
prepare a commit message separately in a file and use "cvs ci -F".
Frankly, a policy that requires stored commit messages containing lines
starting with "CVS: " is not practical.

Would VC users notice the change in behaviour?  I'd say they are
already using erase-buffer or C-w to clear the cvs template lines.  Or
they dug into the code and created a log-edit-done-hook similar to what
I proposed.  And they can continue to do so with no change to observed
behaviour.

And how many users that would be affected are there anyway?  I think it is
likely that there are very few or you would have got complaints in the
last decades.

Anyway, IMHO it is fine to add such a hook function by default to
log-edit-done-hook.  People could customize it away if it really
interferes with their work.

It's also not a big deal to fix up the commit messages with "cvs admin".
I'd imagine people would notice quickly.

--chris