unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
From: Tony Zorman via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
To: Eli Zaretskii <eliz@gnu.org>
Cc: philipk@posteo.net, felician.nemeth@gmail.com,
	60418@debbugs.gnu.org, stefankangas@gmail.com
Subject: bug#60418: [PATCH] Add :vc keyword to use-package
Date: Thu, 04 May 2023 10:13:49 +0200	[thread overview]
Message-ID: <87o7n0fr9e.fsf@hyperspace> (raw)
In-Reply-To: <83ttwun4q4.fsf@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/





  reply	other threads:[~2023-05-04  8:13 UTC|newest]

Thread overview: 50+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-12-29 18:43 bug#60418: [PATCH] Add :vc keyword to use-package Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
     [not found] ` <handler.60418.B.167238381823776.ack@debbugs.gnu.org>
2023-01-14 12:48   ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-03-31 14:13     ` Felician Nemeth
2023-03-31 15:38       ` Philip Kaludercic
2023-04-07 14:11         ` Philip Kaludercic
2023-04-08  8:48           ` Felician Nemeth
2023-04-08  9:06             ` Philip Kaludercic
2023-04-08  9:25               ` Felician Nemeth
2023-04-08 10:41                 ` Philip Kaludercic
2023-04-11 14:10                   ` Felician Nemeth
2023-04-12  7:12                 ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-04-12  7:34                   ` Philip Kaludercic
2023-04-12  9:00                     ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-04-16 15:43                       ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-04-16 16:10                         ` Eli Zaretskii
2023-04-17 19:39                           ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-04-18 12:13                             ` Eli Zaretskii
2023-04-19 17:38                               ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-04-22  9:26                                 ` Eli Zaretskii
2023-04-22 11:34                                   ` Philip Kaludercic
2023-04-23  5:51                                     ` John Wiegley
2023-04-22 11:32                                 ` Philip Kaludercic
2023-04-23  6:07                                   ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-04-23 12:35                                     ` Philip Kaludercic
2023-04-24 12:36                                       ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-05-01 19:43                                         ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-05-01 20:01                                           ` Philip Kaludercic
2023-05-02 13:18                                             ` Ruijie Yu via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-05-02 13:59                                               ` Robert Pluim
2023-05-02 15:09                                               ` Eli Zaretskii
2023-05-02 14:36                                             ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-05-02 12:40                                           ` Eli Zaretskii
2023-05-02 14:22                                             ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-05-02 15:16                                               ` Eli Zaretskii
2023-05-04  8:13                                                 ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors [this message]
2023-05-04 10:39                                                   ` Eli Zaretskii
2023-05-05  5:04                                                   ` Philip Kaludercic
2023-05-05  5:36                                                     ` Eli Zaretskii
2023-05-05  5:49                                                       ` Philip Kaludercic
2023-05-05  6:53                                                         ` Eli Zaretskii
2023-05-05 17:15                                                           ` Philip Kaludercic
2023-05-05 18:45                                                             ` Eli Zaretskii
2023-05-06 18:50                                                               ` Philip Kaludercic
2023-05-06 19:13                                                                 ` Eli Zaretskii
2023-05-07  7:34                                                                   ` Philip Kaludercic
2023-05-06 19:39                                                                 ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-05-07  8:52                                                                   ` Philip Kaludercic
2023-05-16 19:30                                                                     ` Philip Kaludercic
2023-05-17  5:42                                                                       ` Tony Zorman via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-04-16 16:18                         ` Ruijie Yu via Bug reports for GNU Emacs, the Swiss army knife of text editors

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87o7n0fr9e.fsf@hyperspace \
    --to=bug-gnu-emacs@gnu.org \
    --cc=60418@debbugs.gnu.org \
    --cc=eliz@gnu.org \
    --cc=felician.nemeth@gmail.com \
    --cc=philipk@posteo.net \
    --cc=soliditsallgood@mailbox.org \
    --cc=stefankangas@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).