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

[Philip Kaludercic <philipk@posteo.net>]

Eli Zaretskii <eliz@gnu.org> writes:

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

This is true, for package-vc-install, but the idea was not do this for
the :vc keyword to use-package.  My understanding is that the main
interest here is to install packages that are not available via package
archives.  And as use-package is a popular means of bootstrapping a
configuration, it seems the right approach to use the commit of the
latest revision, instead of just any commit to avoid instability.

>> >> 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 have tried to address these issues here:

   By default, this function installs the last revision of the
   package available from its repository.  If REV is a string, it
   describes the revision to install, as interpreted by the VC
   backend.  The special value `:last-release' (interactively, the
   prefix argument), will use the commit of the latest release, if
   it exists.  The latest revision is determined by the latest
   revision to modify the \"Version\" header of the main file.

But I couldn't come up with an elegant way to avoid the passive voice in
the last sentence.

>> I can apply this or any variation thereof to emacs-29.
>
> emacs-29 is fine for documentation changes.