[bug#53163] [PATCH] doc: Document some reasons for/against git tags/commits.

[Maxime Devos <maximedevos@telenet.be>]

[-- Attachment #1.1: Type: text/plain, Size: 449 bytes --]

X-Debbugs-CC: liliana.prikler@gmail.com

Hi,

For <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=53144#53>,
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.

[-- Attachment #1.2: 0001-doc-Document-some-reasons-for-against-git-tags-commi.patch --]
[-- Type: text/x-patch, Size: 2827 bytes --]

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(-)

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


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 260 bytes --]