From 2a4d433b1f194595c819cec88361a1e402ebadb8 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Sat, 6 Nov 2021 13:05:12 +0100
Subject: [PATCH] nixosTest: Add xclip as example of stdout blocker

---
 .../manual/development/writing-nixos-tests.section.md |  7 +++++--
 .../development/writing-nixos-tests.section.xml       | 11 ++++++++---
 .../manual/from_md/release-notes/rl-2111.section.xml  |  7 ++++---
 nixos/doc/manual/release-notes/rl-2111.section.md     |  2 +-
 4 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/nixos/doc/manual/development/writing-nixos-tests.section.md b/nixos/doc/manual/development/writing-nixos-tests.section.md
index a8c54aa66762..d9749d37da79 100644
--- a/nixos/doc/manual/development/writing-nixos-tests.section.md
+++ b/nixos/doc/manual/development/writing-nixos-tests.section.md
@@ -162,7 +162,9 @@ The following methods are available on machine objects:
     If the command detaches, it must close stdout, as `execute` will wait
     for this to consume all output reliably. This can be achieved by
     redirecting stdout to stderr `>&2`, to `/dev/console`, `/dev/null` or
-    a file.
+    a file. Examples of detaching commands are `sleep 365d &`, where the
+    shell forks a new process that can write to stdout and `xclip -i`, where
+    the `xclip` command itself forks without closing stdout.
     Takes an optional parameter `check_return` that defaults to `True`.
     Setting this parameter to `False` will not check for the return code
     and return -1 instead. This can be used for commands that shut down
@@ -183,7 +185,8 @@ The following methods are available on machine objects:
 
     -   Dereferencing unset variables fail the command.
 
-    -   It will wait for stdout to be closed. See `execute`.
+    -   It will wait for stdout to be closed. See `execute` for the
+        implications.
 
 `fail`
 
diff --git a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml
index e0fd90f2bac2..0d523681b639 100644
--- a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml
+++ b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml
@@ -271,8 +271,13 @@ start_all()
           for this to consume all output reliably. This can be achieved
           by redirecting stdout to stderr <literal>&gt;&amp;2</literal>,
           to <literal>/dev/console</literal>,
-          <literal>/dev/null</literal> or a file. Takes an optional
-          parameter <literal>check_return</literal> that defaults to
+          <literal>/dev/null</literal> or a file. Examples of detaching
+          commands are <literal>sleep 365d &amp;</literal>, where the
+          shell forks a new process that can write to stdout and
+          <literal>xclip -i</literal>, where the
+          <literal>xclip</literal> command itself forks without closing
+          stdout. Takes an optional parameter
+          <literal>check_return</literal> that defaults to
           <literal>True</literal>. Setting this parameter to
           <literal>False</literal> will not check for the return code
           and return -1 instead. This can be used for commands that shut
@@ -314,7 +319,7 @@ start_all()
           <listitem>
             <para>
               It will wait for stdout to be closed. See
-              <literal>execute</literal>.
+              <literal>execute</literal> for the implications.
             </para>
           </listitem>
         </itemizedlist>
diff --git a/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml
index 543f3d619804..e3cbb451acdd 100644
--- a/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml
+++ b/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml
@@ -450,9 +450,10 @@
         <para>
           The NixOS VM test framework,
           <literal>pkgs.nixosTest</literal>/<literal>make-test-python.nix</literal>,
-          now requires non-terminating commands such as
-          <literal>succeed(&quot;foo &amp;&quot;)</literal> to close
-          stdout. This can be done with a redirect such as
+          now requires detaching commands such as
+          <literal>succeed(&quot;foo &amp;&quot;)</literal> and
+          <literal>succeed(&quot;foo | xclip -i&quot;)</literal> to
+          close stdout. This can be done with a redirect such as
           <literal>succeed(&quot;foo &gt;&amp;2 &amp;&quot;)</literal>.
           This breaking change was necessitated by a race condition
           causing tests to fail or hang. It applies to all methods that
diff --git a/nixos/doc/manual/release-notes/rl-2111.section.md b/nixos/doc/manual/release-notes/rl-2111.section.md
index 76e7f458d478..cb77c193042a 100644
--- a/nixos/doc/manual/release-notes/rl-2111.section.md
+++ b/nixos/doc/manual/release-notes/rl-2111.section.md
@@ -133,7 +133,7 @@ In addition to numerous new and upgraded packages, this release has the followin
 
 ## Backward Incompatibilities {#sec-release-21.11-incompatibilities}
 
-- The NixOS VM test framework, `pkgs.nixosTest`/`make-test-python.nix`, now requires non-terminating commands such as `succeed("foo &")` to close stdout.
+- The NixOS VM test framework, `pkgs.nixosTest`/`make-test-python.nix`, now requires detaching commands such as `succeed("foo &")` and `succeed("foo | xclip -i")` to close stdout.
   This can be done with a redirect such as `succeed("foo >&2 &")`. This breaking change was necessitated by a race condition causing tests to fail or hang.
   It applies to all methods that invoke commands on the nodes, including `execute`, `succeed`, `fail`, `wait_until_succeeds`, `wait_until_fails`.