From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.bugs Subject: bug#60418: [PATCH] Add :vc keyword to use-package Date: Fri, 05 May 2023 05:04:59 +0000 Message-ID: <878re3cqro.fsf@posteo.net> References: <87zgb6uk2r.fsf@hyperspace> <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> <87o7n0fr9e.fsf@hyperspace> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="2747"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Eli Zaretskii , felician.nemeth@gmail.com, 60418@debbugs.gnu.org, stefankangas@gmail.com To: Tony Zorman Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri May 05 07:06:16 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 1pune3-0000Sj-AE for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 05 May 2023 07:06:15 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1punds-0006UI-Pi; Fri, 05 May 2023 01:06:04 -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 1pundq-0006U6-Nf for bug-gnu-emacs@gnu.org; Fri, 05 May 2023 01:06:02 -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 1pundq-0007gf-FE for bug-gnu-emacs@gnu.org; Fri, 05 May 2023 01:06:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pundq-0002PZ-9x for bug-gnu-emacs@gnu.org; Fri, 05 May 2023 01:06:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Philip Kaludercic Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 05 May 2023 05:06: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.16832631099192 (code B ref 60418); Fri, 05 May 2023 05:06:02 +0000 Original-Received: (at 60418) by debbugs.gnu.org; 5 May 2023 05:05:09 +0000 Original-Received: from localhost ([127.0.0.1]:52863 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1puncy-0002OB-Tn for submit@debbugs.gnu.org; Fri, 05 May 2023 01:05:09 -0400 Original-Received: from mout02.posteo.de ([185.67.36.66]:53575) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1puncw-0002NX-Ph for 60418@debbugs.gnu.org; Fri, 05 May 2023 01:05:08 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id E4276240156 for <60418@debbugs.gnu.org>; Fri, 5 May 2023 07:05:00 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1683263100; bh=+wP/k6Aj9biWLVt/ogjovxWGdxTiZSSXNzJRJQVu4yY=; h=From:To:Cc:Subject:Autocrypt:Date:From; b=Yl0EG58/mEjyasAbm17OwXACuPTDzC3BlO5I7zA2L1ERH67SfGBEEj63qy6ED5WbO 89VbmZJzejf+8/AWNodZkGr1cmjnH0xxd8OGht4Db1rxl6Iq2AjjJoSvKQSOAVlwcK RDCb/e7/NZmdXBDgYDRjOwMNGgsLqTHxTl7NzbMVPz1hwu66dBA/zYvzDpn7VvuDAb Df/SIsfgnKlI+RvMxuBoEyKDMVLfEbwQDt7WZwqlgSRlHNCSOLpHZoXXtkvDRsJ0Mk OQxWGQx1ueFFgMA9huYiX+GMVSZbLnjG320T77q1LxsBCwRDSnWJsLy0jilgcE1sCh NwScMpZR7gPTw== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4QCJXD0p6Bz6tn4; Fri, 5 May 2023 07:05:00 +0200 (CEST) In-Reply-To: <87o7n0fr9e.fsf@hyperspace> (Tony Zorman's message of "Thu, 04 May 2023 10:13:49 +0200") Autocrypt: addr=philipk@posteo.net; keydata= mDMEZBBQQhYJKwYBBAHaRw8BAQdAHJuofBrfqFh12uQu0Yi7mrl525F28eTmwUDflFNmdui0QlBo aWxpcCBLYWx1ZGVyY2ljIChnZW5lcmF0ZWQgYnkgYXV0b2NyeXB0LmVsKSA8cGhpbGlwa0Bwb3N0 ZW8ubmV0PoiWBBMWCAA+FiEEDg7HY17ghYlni8XN8xYDWXahwukFAmQQUEICGwMFCQHhM4AFCwkI BwIGFQoJCAsCBBYCAwECHgECF4AACgkQ8xYDWXahwulikAEA77hloUiSrXgFkUVJhlKBpLCHUjA0 mWZ9j9w5d08+jVwBAK6c4iGP7j+/PhbkxaEKa4V3MzIl7zJkcNNjHCXmvFcEuDgEZBBQQhIKKwYB BAGXVQEFAQEHQI5NLiLRjZy3OfSt1dhCmFyn+fN/QKELUYQetiaoe+MMAwEIB4h+BBgWCAAmFiEE Dg7HY17ghYlni8XN8xYDWXahwukFAmQQUEICGwwFCQHhM4AACgkQ8xYDWXahwukm+wEA8cml4JpK NeAu65rg+auKrPOP6TP/4YWRCTIvuYDm0joBALw98AMz7/qMHvSCeU/hw9PL6u6R2EScxtpKnWof z4oM 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:261050 Archived-At: Tony Zorman 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 >>> 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?