[bug#69787] [PATCH] doc: Add notes about when to use --check

[bug#69787] [PATCH] doc: Add notes about when to use --check

[Skyler Ferris via Guix-patches via]

From: Skyler Ferris <skyvine@protonmail.com>

* doc/contributing.texi: Add notes about using --check when --rounds
is insufficient

Change-Id: I534b3f99181b45c4a955325a4ed59e3e7c651ab6
---
This is a small update to the section about checking that a package is
reproducible, based on a conversation with Carlo Zancanaro on the
help-guix mailing list. While this section does mention guix challenge,
this is used with a separate substitute server.

The notes about what happens with grafts comes from personal
observations from running the commands on my machine. The situation
seems less than ideal but I am not familiar enough with the code to
figure out a way to improve it at the moment. If there is already a
better way of getting the derivation path, especially a way that does
not rely on the build output still being available (the person may have
already closed the build terminal, and knowledge of the build log path
implies knoweldge of the derviation path) please let me know and I will
update this patch accordingly.

 doc/contributing.texi | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index a7d91724fb..aa8421cbb7 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1495,15 +1495,33 @@ Submitting Patches
 typically means checking whether an independent build of the package
 yields the exact same result that you obtained, bit for bit.
 
-A simple way to do that is by building the same package several times in
+If you have not previously built the package, a simple way to check for
+determinism is by building the same package several times in
 a row on your machine (@pxref{Invoking guix build}):
 
 @example
 guix build --rounds=2 my-package
 @end example
 
-This is enough to catch a class of common non-determinism issues, such
-as timestamps or randomly-generated output in the build result.
+If you have already built the package @code{--rounds} is not sufficient
+because @command{guix build} will see that the output is already available
+and build 0 times. Instead, you can use the @code{--check} flag to compare a
+fresh build against the previous output:
+
+@example
+guix build --check my-package
+@end example
+
+However, if the package is grafted (@pxref{Security Updates, grafts}) then
+this will only check the grafts not the original package build. In this case
+you can use the path to the derivation (@code{/gnu/store/<hash>-<descriptor>.drv})
+instead of the package name. The derivation path is printed by @command{guix build}
+when it finishes building a derivation (note that the grafted version of the package
+also has a derivation, so the most recently printed derivation path will not be the
+one that you want to use).
+
+Either of these methods are enough to catch a class of common non-determinism
+issues, such as timestamps or randomly-generated output in the build result.
 
 Another option is to use @command{guix challenge} (@pxref{Invoking guix
 challenge}).  You may run it once the package has been committed and

base-commit: 447e9c96259e8fa15a828de9b2dd3400e2ffafe6
-- 
2.41.0