From patchwork Mon Jan 10 21:08:45 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: M X-Patchwork-Id: 36207 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 51FB527BBEA; Mon, 10 Jan 2022 21:21:19 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-2.7 required=5.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,FREEMAIL_FROM,MAILING_LIST_MULTI,RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL,SPF_HELO_PASS,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id A80B727BBE9 for ; Mon, 10 Jan 2022 21:21:18 +0000 (GMT) Received: from localhost ([::1]:42070 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n726P-0005am-M8 for patchwork@mira.cbaines.net; Mon, 10 Jan 2022 16:21:17 -0500 Received: from eggs.gnu.org ([209.51.188.92]:42526) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n71wq-0004nu-8p for guix-patches@gnu.org; Mon, 10 Jan 2022 16:11:24 -0500 Received: from debbugs.gnu.org ([209.51.188.43]:60499) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1n71vW-000566-Fk for guix-patches@gnu.org; Mon, 10 Jan 2022 16:11:22 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1n71vW-0001aO-3U for guix-patches@gnu.org; Mon, 10 Jan 2022 16:10:02 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#53163] [PATCH] doc: Document some reasons for/against git tags/commits. Resent-From: Maxime Devos Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Mon, 10 Jan 2022 21:10:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 53163 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Liliana Marie Prikler , 53163@debbugs.gnu.org Received: via spool by 53163-submit@debbugs.gnu.org id=B53163.16418489426014 (code B ref 53163); Mon, 10 Jan 2022 21:10:02 +0000 Received: (at 53163) by debbugs.gnu.org; 10 Jan 2022 21:09:02 +0000 Received: from localhost ([127.0.0.1]:53402 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n71uX-0001Yo-Or for submit@debbugs.gnu.org; Mon, 10 Jan 2022 16:09:02 -0500 Received: from andre.telenet-ops.be ([195.130.132.53]:58692) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n71uT-0001YS-Gy for 53163@debbugs.gnu.org; Mon, 10 Jan 2022 16:09:00 -0500 Received: from ptr-bvsjgyhxw7psv60dyze.18120a2.ip6.access.telenet.be ([IPv6:2a02:1811:8c09:9d00:3c5f:2eff:feb0:ba5a]) by andre.telenet-ops.be with bizsmtp id h98q2600F4UW6Th0198vUv; Mon, 10 Jan 2022 22:08:56 +0100 Message-ID: <61f01b2b439db750424023bb2555865ff8139255.camel@telenet.be> From: Maxime Devos Date: Mon, 10 Jan 2022 22:08:45 +0100 In-Reply-To: <3aeda438471930ca3b958a35681a8191cc51fe92.camel@gmail.com> References: <5623ec2b15bf60a51587b0592ad178b2bec3ef37.camel@telenet.be> <3aeda438471930ca3b958a35681a8191cc51fe92.camel@gmail.com> User-Agent: Evolution 3.38.3-1 MIME-Version: 1.0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=telenet.be; s=r22; t=1641848936; bh=f7Y7qBabum9L37mnwQKw6Z+L5MfggMOz3CGBGAo+POs=; h=Subject:From:To:Date:In-Reply-To:References; b=RSDHCBrseXMQzEiXZi8jouynvcsTaPgHf4UB+QqGsJg/SCzIhtxrXsUKWWQjRk+JZ mOuFFXAQAX4bvOedFXXmq63nD+nbXfwUqCi3v9te4l3EDpiuB17HebMSXngMskpAoy Ehv3e1RiHxijgL/W+jEJfr84JSzKTODFV/decRKcC/muPbrAnpGnx74zoXc2T/Ggeb 9OK6kHERvmSqrXPHeIk2IUt3Qmh4M9ygVfB4VtLiVQlU5fr3Xr5hdmjoi/HNkfVfkw XXUU5lC7GAnETly5SVUKpn2X1uvipwvNunghNPQlz4v9l2//HEup3aai7YVW2eglez 2HjzgcW9ZH3dQ== X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: "Guix-patches" X-getmail-retrieved-from-mailbox: Patches A v2 patch with the suggestions applied is attached. Liliana Marie Prikler schreef op ma 10-01-2022 om 20:43 [+0100]: > Hi, > > Am Montag, dem 10.01.2022 um 15:27 +0000 schrieb Maxime Devos: > > For , > > I'd like to be able to reference some section (not specialised > > for Minetest packages, instead more general) explaining when > > and when not to use git tags/commits. > Generally LGTM. > > > +not tag releases at all, in this case commits are unavoidable. In a > > +very few cases (@pxref{Version Numbers}), Guix intentionally uses a > "In a very few cases" looks like a typo. "In few cases" or "In some > exceptional cases" would work well. ‘In some exceptional cases’ looks better to me, applied. > > +Commits make reviewing somewhat trickier, because the reviewer has > > to > > +verify that that the commit actually corresponds to the package > > version. > I'd also add a line regarding the difficulty to verify that a commit > did once belong to a tag as a future reader, but I'm not sure what > exactly to advise here and how. > Done: ‘Likewise, commits make it more difficult for a future reader to verify that a commit did once correspond to a version tag’. > In the particular case of minetest, we > have an external map of "tags" to commits that can be queried, but for > most repos I fear the tags would simply be lost to time. Here "tags" = releases on content.minetest.net, and not Git tags? > > I'm not familiar with "git describe", so the documentation > > doesn't tell when to use "git describe"-style > > tag-number of commits-commit strings. > That's a general question that has not reached a conclusion yet. IIRC > the goal was to make tags more robust by replacing them with git- > describe like tags. This would also make it easier to port between > revisioned commit and tagged one, since one would have to let-bind > commit either way. FWIW, the git updater in (guix upstream) might need to be modified to support the "git describe" style in commit fields, and a linter to verify that the tag+number corresponds to the commit (to avoid some ‘tricking peer review’ issues), but otherwise this seems rather nice to me. I didn't investigate closely though. Greetings, Maxime. From 2887fa418a6f097d7c07380ab6ff6f9452008073 Mon Sep 17 00:00:00 2001 From: Maxime Devos Date: Mon, 10 Jan 2022 15:15:34 +0100 Subject: [PATCH v2] doc: Document some reasons for/against git tags/commits. * doc/guix.texi (origin Reference): Document some points to consider when choosing between commits and tags in 'git-reference'. --- doc/guix.texi | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/doc/guix.texi b/doc/guix.texi index 58ccc75ccf..20192d9e99 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -7514,7 +7514,26 @@ The URL of the Git repository to clone. This string denotes either the commit to fetch (a hexadecimal string), or the tag to fetch. You can also use a ``short'' commit ID or a @command{git describe} style identifier such as -@code{v1.0.1-10-g58d7909c97}. +@code{v1.0.1-10-g58d7909c97}. Often, there is no clear-cut answer to +the question whether a commit or tag should be used. However, there are +some points to consider: + +If upstream removes old tags or mutates existing tags in-place, then a +commit should be used to avoid future breakage. Sometimes upstream does +not tag releases at all, in this case commits are unavoidable. In some +exceptional cases (@pxref{Version Numbers}), Guix intentionally uses a +commit that does not correspond to a release, in which case a commit is +required. + +Some Git repositories only allow checking out tags directly and require +cloning the entire Git repository to checkout a single commit; using a +tag would reduce network traffic in these cases. This does not appear to +be a significant problem in practice, though. + +Commits make reviewing somewhat trickier, because the reviewer has to +verify that that the commit actually corresponds to the package version. +Likewise, commits make it more difficult for a future reader to verify +that a commit did once correspond to a version tag. @item @code{recursive?} (default: @code{#f}) This Boolean indicates whether to recursively fetch Git sub-modules. -- 2.30.2