bug#60418: [PATCH] Add :vc keyword to use-package

[Eli Zaretskii <eliz@gnu.org>]

> From: Tony Zorman <soliditsallgood@mailbox.org>
> Cc: philipk@posteo.net, 60418@debbugs.gnu.org, felician.nemeth@gmail.com,
>  stefankangas@gmail.com
> Date: Tue, 02 May 2023 16:22:17 +0200
> 
> On Tue, May 02 2023 15:40, Eli Zaretskii wrote:
> >> +@code{package-vc-install}.  Notably -- even when not specified --
> >> +@code{:rev} defaults to checking out the last release of the package.
> >> +You can use @code{:rev :newest} to check out the latest commit.
> >> +
> >> +For example,
> >> +
> >> +@example
> >> +@group
> >> +(use-package bbdb
> >> +  :vc (:url "https://git.savannah.nongnu.org/git/bbdb.git"
> >> +       :rev :newest))
> >> +@end group
> >> +@end example
> >> +
> >> +would try -- by invoking @code{package-vc-install} -- to install the
> >> +latest commit of the package @code{foo} from the specified remote.
> >                                       ^^^
> > A typo there.
> >
> > Also, you say above "the latest release", but then "the latest
> > commit".  These two are not the same, and in fact I think talking
> > about "release" here is misleading, since you actually mean "commit".
> > For the same reason, I think the text should explain how to indicate a
> > commit that is not the latest one, because that is also not
> > self-evident, especially since the upstream VCS is not necessarily
> > Git.
> 
> I think the terminology of commit and release I use here are consistent,
> though maybe the wording is perhaps not entirely clear.

Not in my eyes, it isn't.  E.g., look at any GitHub repository: there
are "commits" there, and there are "releases", and they are not the
same.

> If :rev is not explicitly given, then :vc falls back to calling
> package-vc-install (in the case of a non-local upstream) with the
> :last-release keyword in place of its REV argument (which is called a
> revision in the docs). Since package-vc.el freely calls :last-release a
> release of a package, I figured this terminology is appropriate here. It
> is only when :rev :newest is given that I talk about commits, which
> should also be accurate. Or perhaps you mean that I mistakenly talk
> about the latest release in some other place that I've overlooked just
> now?

All I know is that when I've read the documentation you wrote, I asked
myself "what is meant by 'release' here?"  I found the answer when you
later wrote "last commit".

Are you talking about commits?  More generally, what kind of "release
IDs" does :rev accept as its valid value?

I understand that the same confusion could exist elsewhere, but that
doesn't mean we should proliferate it or even live with what we have.
We should instead clarify this in every place where we use this
terminology.

So let's figure out what are these "releases", and then let's examine
the existing and the new documentation and see if we need to get our
terminology right there.

Thanks.