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

Previous Next

To reply to this bug, email your comments to 53163 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: guix-patches <at> gnu.org
Subject: [PATCH] doc: Document some reasons for/against git tags/commits.
Date: Mon, 10 Jan 2022 15:27:55 +0000

[Message part 1 (text/plain, inline)]

X-Debbugs-CC: liliana.prikler <at> 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.

[0001-doc-Document-some-reasons-for-against-git-tags-commi.patch (text/x-patch, attachment)]

[signature.asc (application/pgp-signature, inline)]

Message #8 received at 53163 <at> debbugs.gnu.org (full text, mbox):

From: Liliana Marie Prikler <liliana.prikler <at> gmail.com>
To: Maxime Devos <maximedevos <at> telenet.be>, 53163 <at> debbugs.gnu.org
Subject: Re: [bug#53163] [PATCH] doc: Document some reasons for/against git
 tags/commits.
Date: Mon, 10 Jan 2022 20:43:22 +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.

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

Message #11 received at 53163 <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: Liliana Marie Prikler <liliana.prikler <at> gmail.com>, 53163 <at> debbugs.gnu.org
Subject: Re: [bug#53163] [PATCH] doc: Document some reasons for/against git
 tags/commits.
Date: Mon, 10 Jan 2022 22:08:45 +0100

[Message part 1 (text/plain, inline)]

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.

[v2-0001-doc-Document-some-reasons-for-against-git-tags-co.patch (text/x-patch, inline)]

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

[signature.asc (application/pgp-signature, inline)]

Message #14 received at 53163 <at> debbugs.gnu.org (full text, mbox):

From: Liliana Marie Prikler <liliana.prikler <at> gmail.com>
To: Maxime Devos <maximedevos <at> telenet.be>, 53163 <at> debbugs.gnu.org
Subject: Re: [bug#53163] [PATCH] doc: Document some reasons for/against git
 tags/commits.
Date: Mon, 10 Jan 2022 22:36:14 +0100

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

Message #17 received at 53163 <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: Maxime Devos <maximedevos <at> telenet.be>
Cc: liliana.prikler <at> gmail.com, 53163 <at> debbugs.gnu.org
Subject: Re: bug#53163: [PATCH] doc: Document some reasons for/against git
 tags/commits.
Date: Wed, 26 Jan 2022 12:40:05 +0100

Hi!

Maxime Devos <maximedevos <at> telenet.be> skribis:

> From 460c25842204936eaf8ead3ab37049e4b93cf086 Mon Sep 17 00:00:00 2001
> From: Maxime Devos <maximedevos <at> 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’.

Message #20 received at 53163 <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: 53163 <at> debbugs.gnu.org
Subject: Re: [PATCH] doc: Document some reasons for/against git tags/commits.
Date: Thu, 30 Jun 2022 11:35:44 +0200

[Message part 1 (text/plain, inline)]

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

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.