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

[Maxime Devos <maximedevos@telenet.be>]

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

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 <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.
> 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.

[-- Attachment #1.2: Type: text/x-patch, Size: 2076 bytes --]

From 2887fa418a6f097d7c07380ab6ff6f9452008073 Mon Sep 17 00:00:00 2001
From: Maxime Devos <maximedevos@telenet.be>
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


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