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

[Tony Zorman via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

I suppose Philip would be more qualified than me to answer this, but
I'll try.

On Tue, May 02 2023 18:16, Eli Zaretskii wrote:
>> 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.

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.

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

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

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

-- 
Tony Zorman | https://tony-zorman.com/