From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Tony Zorman via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: bug#60418: [PATCH] Add :vc keyword to use-package Date: Thu, 04 May 2023 10:13:49 +0200 Message-ID: <87o7n0fr9e.fsf@hyperspace> References: <87zgb6uk2r.fsf@hyperspace> <87y1n3zsro.fsf@posteo.net> <871qku220f.fsf@betli.tmit.bme.hu> <874jpq920b.fsf@posteo.net> <87cz4ezpwi.fsf@betli.tmit.bme.hu> <87h6tlinft.fsf@hyperspace> <87r0spa712.fsf@posteo.net> <87edopiif5.fsf@hyperspace> <87wn2bzvcp.fsf@hyperspace> <835y9vbyfr.fsf@gnu.org> <87mt36uwl8.fsf@hyperspace> <83ttxd8k1z.fsf@gnu.org> <87v8hrn56l.fsf@hyperspace> <87cz3w2lvb.fsf@posteo.net> <87jzy3ku6u.fsf@hyperspace> <87bkje93ou.fsf@posteo.net> <87y1mhihhy.fsf@hyperspace> <87ildbet2d.fsf@hyperspace> <831qjyoqj5.fsf@gnu.org> <87h6suolt2.fsf@hyperspace> <83ttwun4q4.fsf@gnu.org> Reply-To: Tony Zorman Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="35019"; mail-complaints-to="usenet@ciao.gmane.io" Cc: philipk@posteo.net, felician.nemeth@gmail.com, 60418@debbugs.gnu.org, stefankangas@gmail.com To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu May 04 10:15:51 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1puU7x-0008wi-OW for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 04 May 2023 10:15:49 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1puU7F-0002yG-FV; Thu, 04 May 2023 04:15:05 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1puU7D-0002xh-0T for bug-gnu-emacs@gnu.org; Thu, 04 May 2023 04:15:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1puU7C-0003Gw-Mi for bug-gnu-emacs@gnu.org; Thu, 04 May 2023 04:15:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1puU7C-0000WE-Ec for bug-gnu-emacs@gnu.org; Thu, 04 May 2023 04:15:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Tony Zorman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 04 May 2023 08:15:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 60418 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 60418-submit@debbugs.gnu.org id=B60418.16831880461880 (code B ref 60418); Thu, 04 May 2023 08:15:02 +0000 Original-Received: (at 60418) by debbugs.gnu.org; 4 May 2023 08:14:06 +0000 Original-Received: from localhost ([127.0.0.1]:48448 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1puU6H-0000UF-VX for submit@debbugs.gnu.org; Thu, 04 May 2023 04:14:06 -0400 Original-Received: from mout-p-103.mailbox.org ([80.241.56.161]:34284) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1puU6D-0000Tb-A9 for 60418@debbugs.gnu.org; Thu, 04 May 2023 04:14:04 -0400 Original-Received: from smtp1.mailbox.org (smtp1.mailbox.org [10.196.197.1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-103.mailbox.org (Postfix) with ESMTPS id 4QBmmd0C1mz9snc; Thu, 4 May 2023 10:13:53 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mailbox.org; s=mail20150812; t=1683188033; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=HknSJoGX8ugYYTzP63+Swc3MH4UijQCD9gZVH8fjdTs=; b=jSG+/HT9XZjxzWzHnkjSNgzSSvCKyo/1RMUBc/A42rt2qTfD/Vq072CjKQhd46LcuCcAue tHpviKyiaQxqfUU13ageopykpxxN7VqQBwDy4g8o6pmiMfCsMBvhVBWhZYEFcM3FoKZCQe UYUIkRN43O8PejQj5vT9vQfpSFc0w6+7qUK/SBvFJ/ByMa8yn4uHg0D1HU/KoMksN80dTB Ec4EMhZDkiNcZANMeIWLHB/ZbELkYM2V1TE457RasAJbSh6fl5+sI6ktsfamO78OVGTcuU MneilVjDT4C/TZTf2WzKNlxLFpB5H6mrivOly2ehc4kHb8jaWGbic+DiwVW+/Q== In-Reply-To: <83ttwun4q4.fsf@gnu.org> X-MBO-RS-META: 71by8bmzq54n1jhj89fz5ugbu88h7zfe X-MBO-RS-ID: ca7226b2fabd1b32ed6 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:261002 Archived-At: 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 >> 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/