From 0ea62670eda39ebeaff5335fd8225707ec27e7a3 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 1 Dec 2022 04:40:02 +0100
Subject: [PATCH] move documentation on `auto-allocate-uids` to options docs

this is where it belongs and can be found together with the other
options.
---
 doc/manual/src/release-notes/rl-next.md | 42 +++++++++++--------------
 src/libstore/globals.hh                 | 36 +++++++++++++++++----
 2 files changed, 48 insertions(+), 30 deletions(-)

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 8b314b5f6..bf51aa1f7 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -12,43 +12,37 @@
   ([#7260](https://github.com/NixOS/nix/pull/7260)).
 
 * Nix can now automatically pick UIDs for builds, removing the need to
-  create `nixbld*` user accounts. These UIDs are allocated starting at
-  872415232 (0x34000000) on Linux and 56930 on macOS.
+  create `nixbld*` user accounts.
 
-  This is an experimental feature. To enable it, add the following to
-  `nix.conf`:
+  See [`auto-allocate-uids`].
 
-  ```
-  extra-experimental-features = auto-allocate-uids
-  auto-allocate-uids = true
-  ```
+  [`auto-allocate-uids`]: (../command-ref/conf-file.md#conf-auto-allocate-uids)
 
 * On Linux, Nix can now run builds in a user namespace where the build
-  runs as root (UID 0) and has 65,536 UIDs available. This is
-  primarily useful for running containers such as `systemd-nspawn`
-  inside a Nix build. For an example, see
-  https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix.
+  runs as root (UID 0) and has 65,536 UIDs available.
 
-  A build can enable this by requiring the `uid-range` system feature,
-  i.e. by setting the derivation attribute
+  <!-- FIXME: move this to its own section about system features -->
+
+  This is primarily useful for running containers such as `systemd-nspawn`
+  inside a Nix build. For an example, see [`tests/systemd-nspawn/nix`][nspawn].
+
+  [nspawn]: https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix.
+
+  A build can enable this by by setting the derivation attribute:
 
   ```
   requiredSystemFeatures = [ "uid-range" ];
   ```
 
-  The `uid-range` system feature requires the `auto-allocate-uids`
-  setting to be enabled (see above).
+  The `uid-range` [system feature] requires the [`auto-allocate-uids`]
+  setting to be enabled.
+
+  [system feature]: (../command-ref/conf-file.md#conf-system-features),
 
 * On Linux, Nix has experimental support for running builds inside a
-  cgroup. It can be enabled by adding
+  cgroup.
 
-  ```
-  extra-experimental-features = cgroups
-  use-cgroups = true
-  ```
-
-  to `nix.conf`. Cgroups are required for derivations that require the
-  `uid-range` system feature.
+  See [`use-cgroups`](../command-ref/conf-file.md#conf-use-cgroups).
 
 * `nix build --json` now prints some statistics about top-level
   derivations, such as CPU statistics when cgroups are enabled.
diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh
index b40dcfa77..b61a34461 100644
--- a/src/libstore/globals.hh
+++ b/src/libstore/globals.hh
@@ -284,7 +284,21 @@ public:
         )"};
 
     Setting<bool> autoAllocateUids{this, false, "auto-allocate-uids",
-        "Whether to allocate UIDs for builders automatically."};
+        R"(
+          Whether to allocate UIDs for builders automatically.
+
+          These UIDs are allocated starting at 872415232 (0x34000000) on Linux and 56930 on macOS.
+
+          > **Warning**
+          > This is an experimental feature.
+
+          To enable it, add the following to [`nix.conf`](#):
+
+          ```
+          extra-experimental-features = auto-allocate-uids
+          auto-allocate-uids = true
+          ```
+        )"};
 
     Setting<uint32_t> startId{this,
         #if __linux__
@@ -308,11 +322,21 @@ public:
     Setting<bool> useCgroups{
         this, false, "use-cgroups",
         R"(
-          Whether to execute builds inside cgroups. Cgroups are
-          enabled automatically for derivations that require the
-          `uid-range` system feature.
-        )"
-    };
+          Whether to execute builds inside cgroups.
+          Only on Linux with systemd.
+
+          cgroups are required and enabled automatically for derivations that require the `uid-range` system feature.
+
+          > **Warning**
+          > This is an experimental feature.
+
+          To enable it, add the following to [`nix.conf`](#):
+
+          ```
+          extra-experimental-features = cgroups
+          use-cgroups = true
+          ```
+        )"};
     #endif
 
     Setting<bool> impersonateLinux26{this, false, "impersonate-linux-26",