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