From 02555cd0bd66f9606d4e336fdae05e3c14f36d19 Mon Sep 17 00:00:00 2001
From: Scott Edlund <sedlund@users.noreply.github.com>
Date: Thu, 24 Apr 2025 22:07:40 +0800
Subject: [PATCH] nixos/systemd: clarify what enableStrictShellChecks checks

the specifics of this option are in the release notes, but bring
them into the documentation.
---
 nixos/lib/systemd-unit-options.nix    | 18 +++++++++++++++---
 nixos/modules/system/boot/systemd.nix | 27 ++++++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/nixos/lib/systemd-unit-options.nix b/nixos/lib/systemd-unit-options.nix
index 6c93bfddfa52..27d2e5d18391 100644
--- a/nixos/lib/systemd-unit-options.nix
+++ b/nixos/lib/systemd-unit-options.nix
@@ -398,9 +398,21 @@ rec {
 
         enableStrictShellChecks = mkOption {
           type = types.bool;
-          description = "Enable running shellcheck on the generated scripts for this unit.";
-          # The default gets set in systemd-lib.nix because we don't have access to
-          # the full NixOS config here.
+          description = ''
+            Enable running `shellcheck` on the generated scripts for this unit.
+
+            When enabled, scripts generated by the unit will be checked with
+            `shellcheck` and any errors or warnings will cause the build to
+            fail.
+
+            This affects all scripts that have been created through the
+            `script`, `reload`, `preStart`, `postStart`, `preStop` and
+            `postStop` options for systemd services. This does not affect
+            command lines passed directly to `ExecStart`, `ExecReload`,
+            `ExecStartPre`, `ExecStartPost`, `ExecStop` or `ExecStopPost`.
+          '';
+          # The default gets set in systemd-lib.nix because we don't have
+          # access to the full NixOS config here.
           defaultText = literalExpression "config.systemd.enableStrictShellChecks";
         };
 
diff --git a/nixos/modules/system/boot/systemd.nix b/nixos/modules/system/boot/systemd.nix
index 24c317bcc46d..7f998c1de49c 100644
--- a/nixos/modules/system/boot/systemd.nix
+++ b/nixos/modules/system/boot/systemd.nix
@@ -226,7 +226,32 @@ in
     package = mkPackageOption pkgs "systemd" { };
 
     enableStrictShellChecks = mkEnableOption "" // {
-      description = "Whether to run shellcheck on the generated scripts for systemd units.";
+      description = ''
+        Whether to run `shellcheck` on the generated scripts for systemd
+        units.
+
+        When enabled, all systemd scripts generated by NixOS will be checked
+        with `shellcheck` and any errors or warnings will cause the build to
+        fail.
+
+        This affects all scripts that have been created through the `script`,
+        `reload`, `preStart`, `postStart`, `preStop` and `postStop` options for
+        systemd services. This does not affect command lines passed directly
+        to `ExecStart`, `ExecReload`, `ExecStartPre`, `ExecStartPost`,
+        `ExecStop` or `ExecStopPost`.
+
+        It therefore also does not affect systemd units that are coming from
+        packages and that are not defined through the NixOS config. This option
+        is disabled by default, and although some services have already been
+        fixed, it is still likely that you will encounter build failures when
+        enabling this.
+
+        We encourage people to enable this option when they are willing and
+        able to submit fixes for potential build failures to Nixpkgs. The
+        option can also be enabled or disabled for individual services using
+        the `enableStrictShellChecks` option on the service itself, which will
+        take precedence over the global setting.
+      '';
     };
 
     units = mkOption {