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

[Eli Zaretskii]

> From: Philip Kaludercic <philipk@posteo.net>
> Cc: soliditsallgood@mailbox.org,  60418@debbugs.gnu.org,
>   felician.nemeth@gmail.com,  stefankangas@gmail.com
> Date: Fri, 05 May 2023 05:49:26 +0000
> 
> >> 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?
> 
> No, the commit of the latest release is interpreted the same way as
> elpa-admin.el does, namely the last revision that modified the "Version"
> header.  If no such commit can be found, then a message is printed out
> and the installation continues under the assumption that the package is
> using a rolling-release model.

I thought package-vc-install is used (or at least can be used) to
fetch the latest HEAD from the upstream repository?  I even thought
this was its main raison d'être?

If that's not true, does it mean we have no means for package users to
track the latest development code of a package?

> >> Are there any other places where we can fix this confusion?
> >
> > I guess the documentation of package-vc-install shares these issues?
> 
> How does this sound like to you:
> 
> diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el
> index 8f62e7d65f3..b28e33b3b89 100644
> --- a/lisp/emacs-lisp/package-vc.el
> +++ b/lisp/emacs-lisp/package-vc.el
> @@ -747,11 +747,14 @@ package-vc-install
>  symbol whose name is the package name, and the URL for the
>  package will be taken from the package's metadata.
>  
> -By default, this function installs the last version of the package
> -available from its repository, but if REV is given and non-nil, it
> -specifies the revision to install.  If REV has the special value
> -`:last-release' (interactively, the prefix argument), that stands
> -for the last released version of the package.
> +By default, this function installs the last revision of the
> +package available from its repository, but if REV is given and
> +non-nil, it specifies the revision to install.  If REV has the
> +special value `:last-release' (interactively, the prefix
> +argument), an attempt is made to find the revision of the latest
> +release.  This is done by looking up the last revision that
> +modified the \"Version\" header, as described in the Info
> +node `(elisp) Library Headers'.

First, too much of passive voice.
More importantly, this still doesn't tell:

  . what is "the last revision", the one installed if REV is omitted?
  . what are possible values of REV, in addition to :last-release, and
    how are those values interpreted, in VCS terms?

> I can apply this or any variation thereof to emacs-29.

emacs-29 is fine for documentation changes.