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

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.

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

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

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