doc: Improve instructions to minimize unexpected test failures.

* doc/contributing.texi (Building from Git): Suggest `guix shell --pure`
as that is currenlty the only way to make the tests pass on the first run.
(Running the Test Suite): Explain which test failures are expected depending
on each setup.

Change-Id: I3425879dcd2a71c2e3c2fd00b55c819447ac9437
Signed-off-by: Ludovic Courtès <ludo@gnu.org>
Modified-by: Ludovic Courtès <ludo@gnu.org>
Merges: #9408

1 files changed, 32 insertions, 17 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 95ba08c508c..576aee8a816 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -175,24 +175,16 @@ all the dependencies and appropriate environment variables are set up to
 hack on Guix:
 
 @example
-guix shell -D guix -CPW
+guix shell -D guix --pure
 @end example
 
 or even, from within a Git worktree for Guix:
 
 @example
 echo $(pwd) >> ~/.config/guix/shell-authorized-directories
-guix shell -CPW
+guix shell --pure
 @end example
 
-If @option{-C} (short for @option{--container}) is not supported on your
-system, try @command{--pure} instead of @option{-CPW}.
-@xref{Invoking guix shell}, for more information on that command.
-
-Most of the test suite runs without an internet connection. The @option{-N}
-(short for @option{--network}) can be added to the @code{guix shell} command
-to run the tests that require internet access.
-
 If you are unable to use Guix when building Guix from a checkout, the
 following are the required packages in addition to those mentioned in the
 installation instructions (@pxref{Requirements}).
@@ -210,7 +202,7 @@ On Guix, other development tools, like @code{strace}, can be included by
 giving them as extra arguments to @command{guix shell}:
 
 @example
-guix shell -D guix -CPW strace
+guix shell --pure -D guix strace
 @end example
 
 From there you can generate the build system infrastructure
@@ -261,18 +253,14 @@ right @code{localstatedir} and @code{sysconfdir} values, which get
 recorded in the @code{(guix config)} Guile module.
 
 Finally, you can build Guix and, if you feel so inclined, run the tests
-(@pxref{Running the Test Suite}):
+(depending on how you setup your environment, some tests might fail,
+@pxref{Running the Test Suite}):
 
 @example
 make
 make check
 @end example
 
-@noindent
-If anything fails, take a look at installation instructions
-(@pxref{Installation}) or send a message to the
-@email{guix-devel@@gnu.org, mailing list}.
-
 From there on, you can authenticate all the commits included in your
 checkout by running:
 
@@ -345,6 +333,33 @@ suite, type:
 make check
 @end example
 
+Some tests might fail or be skipped, depending on your environment.
+For example, many tests require Internet access to download test
+binaries into the temporary store used for testing.
+
+Assuming you set up your environment with @command{guix shell},
+this is what you can expect:
+
+@table @option
+@item --pure
+all tests should either pass or be skipped.  This will also
+set up the test store;
+@item -CPWN
+all tests should either pass or be skipped and this should
+also set up the test store@footnote{At the time of writing, June 2026,
+some tests might fail in a @option{-CPWN} shell; those are
+@url{https://codeberg.org/guix/guix/issues/9381, bugs}.};
+@item -CPW
+all network tests should automatically be skipped, but tests
+that require the test store are run, so those will fail unless the test store
+has been set up during an earlier test run with network access.
+@end table
+
+@quotation Note
+Some tests are skipped for other reasons, for example because they are
+only applicable for a specific system.
+@end quotation
+
 Test cases can run in parallel: you can use the @code{-j} option of
 GNU@tie{}make to speed things up.  The first run may take a few minutes
 on a recent machine; subsequent runs will be faster because the store