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

[Philip Kaludercic]

Tony Zorman <soliditsallgood@mailbox.org> writes:

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

Sorry, I forgot the respond to this exchange.

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

How about we just say "the commit of the latest release"?  That would
avoid confusing the reader into believing that we are fetching the code
via some "official" release-channel or anything like that, while still
indicating that this is not just any commit.

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

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?