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