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

[Eli Zaretskii]

> From: Tony Zorman <soliditsallgood@mailbox.org>
> Cc: philipk@posteo.net, 60418@debbugs.gnu.org, felician.nemeth@gmail.com,
>  stefankangas@gmail.com
> Date: Thu, 04 May 2023 10:13:49 +0200
> 
> > 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.
> 
> 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.

OK, then this should be documented.  Specifically, it is important to
explain that the default is the latest _commit_ (a.k.a. HEAD) of the
default branch, whereas specific releases are those that bump the
Version: tag in the main ELisp file.

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

Any value other than a commit hash?  E.g., are tags supported?

And how will the user know which commit hash or tag to specify given
the value of a Version: tag in the main file?  We should document that
as well.

Thanks.