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