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

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

[Maxime Devos]

[-- 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 --]

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

[Liliana Marie Prikler]

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.

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

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

Cheers

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

[Maxime Devos]

[-- 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 --]

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

[Liliana Marie Prikler]

Hi,

Am Montag, dem 10.01.2022 um 22:08 +0100 schrieb Maxime Devos:
> A v2 patch with the suggestions applied is attached.
LGTM, but let's wait for more opinions.  Since this does concern Guix
as a whole I don't want to be the sole dictator here.

> 
> >   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?
Yep, "tags" = contentdb releases, I forgot the terminology here :)
> > 

> > 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.
Yeah, in my opinion we'd also want a (git-tag VERSION COMMIT) procedure
to produce it, which is definitely c-u material.  And obviously long
hashes would be required.

Cheers

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

[Ludovic Courtès]

Hi!

Maxime Devos <maximedevos@telenet.be> skribis:

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

I think we should separate reference material from guidelines.  Perhaps
this should rather go under “Packaging Guidelines”, next to “Version
Numbers”?

The problem is that it explains the tradeoff but, as you write, does not
provide any answer.  So it’s not strictly speaking a “guideline” but may
still be useful to have though.

Ludo’.

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

[Maxime Devos]

[-- Attachment #1: Type: text/plain, Size: 2574 bytes --]

> I think we should separate reference material from guidelines. 
> Perhaps this should rather go under “Packaging Guidelines”, next to
> “Version Numbers”?

I suppose for consistency with the ‘Packaging Guidelines’ chapter, I
could move it there, though I'd like to add a cross-reference to the
description of ‘commit’ in git-reference for convenience, e.g. maybe:

     ‘commit’
          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 ‘git describe’ style identifier such as
          ‘v1.0.1-10-g58d7909c97’.  **To decide between choosing a
          commit or a tag, the guidelines in [cross-reference] may be
          useful.**

?

(At first I'd have preferred to not separate reference material to keep
all information on commits together, but on second thought separating
them would be more orderly and it's not like we don't have cross-
references, so maybe it would be better to split ...)

> Toggle quote (4 lines)
> > +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.  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.

FWIW, the same holds (though maybe to a lesser degree in practice?) for
hashes and tarballs), not specific to git.

Anyway, SWH keeps this historical information, e.g. here are two lists
of tags->commits of the Minetest repo at two different points in time:

* https://archive.softwareheritage.org/browse/snapshot/d063751724753b97de41a34aa3d1779186530bb4/releases/?origin_url=https://github.com/minetest/minetest&timestamp=2020-01-18T00:07:33Z
* https://archive.softwareheritage.org/browse/snapshot/81e0233dbaf285922bef2281f4e5cbbe5fbc7ea0/releases/?origin_url=https://github.com/minetest/minetest&timestamp=2022-06-25T04:01:20Z

That assumes trusting SWH to be correct of course (and a bit of a
SPOF though I don't expect problems), but with some work, things can
be verified even for repos that delete tags.

Anyway, any remaining comments or a second opinion?  (Would like more
than three people for something like this?)

Greetings,
Maxime.

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