(address . guix-patches@gnu.org)
X-Debbugs-CC: liliana.prikler@gmail.com
Hi,
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.
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.
Greetings,
Maxime.
From 460c25842204936eaf8ead3ab37049e4b93cf086 Mon Sep 17 00:00:00 2001
From: Maxime Devos <maximedevos@telenet.be>
Date: Mon, 10 Jan 2022 15:15:34 +0100
Subject: [PATCH] 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 | 19 ++++++++++++++++++-
1 file changed, 18 insertions(+), 1 deletion(-)
Toggle diff (47 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 58ccc75ccf..5c51dc1361 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7514,7 +7514,24 @@ 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 a
+very few 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.
@item @code{recursive?} (default: @code{#f})
This Boolean indicates whether to recursively fetch Git sub-modules.
base-commit: 9fd4f4b09cc0495d6b1418f171ff738a1086cc00
prerequisite-patch-id: 9e070819096a5b3df220706866de3f9a24700add
prerequisite-patch-id: 9e081caf6df1e9b7fa4ecf0e816089cb65897d7b
prerequisite-patch-id: 8fa14cb2d1fcc4b4d5be227bf8a2691a912500c0
prerequisite-patch-id: 3d4bf2cbd36e29a031c6ccd13fdf4edd51b67652
prerequisite-patch-id: b740911b2fab6e87f003e13ce21d3c726d7ffeb6
prerequisite-patch-id: 2495e12d0efbf42fe847e7411a9c7abbf6b09c38
prerequisite-patch-id: f281231d96059179b6b891d999dda798b099e2fb
prerequisite-patch-id: c60b330f96721da1f7790dd29b5d428e312e7b2e
prerequisite-patch-id: a3ab55eaf0dece586c513fa5671414ff902eb1cd
prerequisite-patch-id: ff47ed0086837f18293d67e5edd01ca14c6f84c9
prerequisite-patch-id: 2c805f40c37fed3eb8e69456d4c90c0a75b643be
prerequisite-patch-id: dfc9534307fd4365205bcd22cea57c3e196b29e8
prerequisite-patch-id: 5035d75f6463dbcc8d7e29782ba9b1f7a5867c42
--
2.30.2
-----BEGIN PGP SIGNATURE-----
iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYdxQdBccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7o53AP43+6G6YdJ705hmz611HxrMvePD
rODF366NzYuD6kZeTgD/aN5uu0I0357cp9WrEhAr04xa2d8G8Pgtu75aNr5hNw4=
=5kAN
-----END PGP SIGNATURE-----