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

[Eli Zaretskii <eliz@gnu.org>]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: Eli Zaretskii <eliz@gnu.org>,  60418@debbugs.gnu.org,
>   felician.nemeth@gmail.com,  stefankangas@gmail.com
> Date: Fri, 05 May 2023 05:04:59 +0000
> 
> Tony Zorman <soliditsallgood@mailbox.org> writes:
> 
> > You're right, but I don't think I'm using them as synonyms. There is a
> > big difference between
> >
> >     (package-vc-install "foo")
> >
> > which installs the latest "commit" (or revision, which I'm actually
> > using as a synonym to commit) of a package, and
> >
> >     (package-vc-install "foo" :last-release)
> >
> > which installs the latest "release". A release, as defined by
> > package-vc.el seems to be 'the latest revision that bumps the "Version"
> > tag.' It is queried in the package-vc--release-rev function, and
> > actually retrieved in vc-retrieve-tag. The "Version" tag is, I think,
> > just the "Version: XXX" string that's specified in the top comment of
> > the main elisp file of the respective repository.
> 
> How about we just say "the commit of the latest release"?

When package-vc-install is used, what is "the latest release"? isn't
that the HEAD of the default branch?  IOW, what about packages that
make no releases at all?

> >> 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?
> >
> > The :rev keyword accepts the same as REV of package-vc-install, which is
> > either
> >
> >   - nil, signaling that the latest commit should be installed,
> >
> >   - :last-release, signaling that the last release should be installed,
> >     or
> >
> >   - a "version string" appropriate for the respective version control
> >     system, specifying that version (e.g., a specific commit hash).
> 
> All correct.
> 
> >> 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.
> >
> > I totally agree, and I think the fact that "release" means "when has the
> > release version as specified in the main .el file changed" should be
> > documented somewhere (if it is I didn't see it). Sorry that this has
> > caused so much confusion.
> 
> Are there any other places where we can fix this confusion?

I guess the documentation of package-vc-install shares these issues?