modules/mkRemovedOptionModule: add replacement doc

When displaying a warning about a removed Option we should always
include reasoning why it was removed and how to get the same
functionality without it.

Introduces such a description argument and patches occurences (mostly
with an empty string).

startGnuPGAgent: further notes on replacement

lib/modules.nix

@@ -503,19 +503,25 @@ rec {
   /* Return a module that causes a warning to be shown if the
      specified option is defined. For example,
 
-       mkRemovedOptionModule [ "boot" "loader" "grub" "bootDevice" ]
+       mkRemovedOptionModule [ "boot" "loader" "grub" "bootDevice" ] "<replacement instructions>"
 
      causes a warning if the user defines boot.loader.grub.bootDevice.
+
+     replacementInstructions is a string that provides instructions on
+     how to achieve the same functionality without the removed option,
+     or alternatively a reasoning why the functionality is not needed.
+     replacementInstructions SHOULD be provided!
   */
-  mkRemovedOptionModule = optionName:
+  mkRemovedOptionModule = optionName: replacementInstructions:
     { options, ... }:
     { options = setAttrByPath optionName (mkOption {
         visible = false;
       });
       config.warnings =
         let opt = getAttrFromPath optionName options; in
-        optional opt.isDefined
+        optional opt.isDefined ''
-          "The option definition `${showOption optionName}' in ${showFiles opt.files} no longer has any effect; please remove it.";
+            The option definition `${showOption optionName}' in ${showFiles opt.files} no longer has any effect; please remove it.
+            ${replacementInstructions}'';
     };
 
   /* Return a module that causes a warning to be shown if the

nixos/doc/manual/release-notes/rl-1603.xml

@@ -385,6 +385,41 @@ services.syncthing = {
       the github issue</link>.
     </para>
   </listitem>
+
+  <listitem>
+    <para>
+      The <literal>services.xserver.startGnuPGAgent</literal> option has been removed.
+      GnuPG 2.1.x changed the way the gpg-agent works, and that new approach no
+      longer requires (or even supports) the "start everything as a child of the
+      agent" scheme we've implemented in NixOS for older versions.
+      To configure the gpg-agent for your X session, add the following code to
+      <filename>~/.bashrc</filename> or some file that’s sourced when your shell is started:
+    <programlisting>
+GPG_TTY=$(tty)
+export GPG_TTY
+    </programlisting>
+      If you want to use gpg-agent for SSH, too, add the following to your session
+      initialization (e.g. <literal>displayManager.sessionCommands</literal>)
+    <programlisting>
+gpg-connect-agent /bye
+unset SSH_AGENT_PID
+export SSH_AUTH_SOCK="''${HOME}/.gnupg/S.gpg-agent.ssh"
+    </programlisting>
+      and make sure that
+    <programlisting>
+enable-ssh-support
+    </programlisting>
+      is included in your <filename>~/.gnupg/gpg-agent.conf</filename>.
+      You will need to use <command>ssh-add</command> to re-add your ssh keys.
+      If gpg’s automatic transformation of the private keys to the new format fails,
+      you will need to re-import your private keyring as well:
+    <programlisting>
+gpg --import ~/.gnupg/secring.gpg
+    </programlisting>
+    The <command>gpg-agent(1)</command> man page has more details about this subject,
+    i.e. in the "EXAMPLES" section.
+    </para>
+  </listitem>
 </itemizedlist>
 
 

nixos/modules/rename.nix

@@ -29,7 +29,7 @@ with lib;
     (mkRenamedOptionModule [ "jobs" ] [ "systemd" "services" ])
 
     (mkRenamedOptionModule [ "services" "gitlab" "stateDir" ] [ "services" "gitlab" "statePath" ])
-    (mkRemovedOptionModule [ "services" "gitlab" "satelliteDir" ])
+    (mkRemovedOptionModule [ "services" "gitlab" "satelliteDir" ] "")
 
     # Old Grub-related options.
     (mkRenamedOptionModule [ "boot" "initrd" "extraKernelModules" ] [ "boot" "initrd" "kernelModules" ])
@@ -112,21 +112,21 @@ with lib;
     (mkRenamedOptionModule [ "services" "iodined" "domain" ] [ "services" "iodine" "server" "domain" ])
     (mkRenamedOptionModule [ "services" "iodined" "ip" ] [ "services" "iodine" "server" "ip" ])
     (mkRenamedOptionModule [ "services" "iodined" "extraConfig" ] [ "services" "iodine" "server" "extraConfig" ])
-    (mkRemovedOptionModule [ "services" "iodined" "client" ])
+    (mkRemovedOptionModule [ "services" "iodined" "client" ] "")
 
     # Options that are obsolete and have no replacement.
-    (mkRemovedOptionModule [ "boot" "initrd" "luks" "enable" ])
+    (mkRemovedOptionModule [ "boot" "initrd" "luks" "enable" ] "")
-    (mkRemovedOptionModule [ "programs" "bash" "enable" ])
+    (mkRemovedOptionModule [ "programs" "bash" "enable" ] "")
-    (mkRemovedOptionModule [ "services" "samba" "defaultShare" ])
+    (mkRemovedOptionModule [ "services" "samba" "defaultShare" ] "")
-    (mkRemovedOptionModule [ "services" "syslog-ng" "serviceName" ])
+    (mkRemovedOptionModule [ "services" "syslog-ng" "serviceName" ] "")
-    (mkRemovedOptionModule [ "services" "syslog-ng" "listenToJournal" ])
+    (mkRemovedOptionModule [ "services" "syslog-ng" "listenToJournal" ] "")
-    (mkRemovedOptionModule [ "ec2" "metadata" ])
+    (mkRemovedOptionModule [ "ec2" "metadata" ] "")
-    (mkRemovedOptionModule [ "services" "openvpn" "enable" ])
+    (mkRemovedOptionModule [ "services" "openvpn" "enable" ] "")
-    (mkRemovedOptionModule [ "services" "printing" "cupsFilesConf" ])
+    (mkRemovedOptionModule [ "services" "printing" "cupsFilesConf" ] "")
-    (mkRemovedOptionModule [ "services" "printing" "cupsdConf" ])
+    (mkRemovedOptionModule [ "services" "printing" "cupsdConf" ] "")
-    (mkRemovedOptionModule [ "services" "xserver" "startGnuPGAgent" ])
+    (mkRemovedOptionModule [ "services" "xserver" "startGnuPGAgent" ]
-    (mkRemovedOptionModule [ "services" "phpfpm" "phpIni" ])
+      "See the 16.03 release notes for more information.")
-    (mkRemovedOptionModule [ "services" "dovecot2" "package" ])
+    (mkRemovedOptionModule [ "services" "phpfpm" "phpIni" ] "")
-
+    (mkRemovedOptionModule [ "services" "dovecot2" "package" ] "")
   ];
 }

nixos/modules/services/x11/display-managers/default.nix

@@ -305,7 +305,8 @@ in
   };
 
   imports = [
-   (mkRemovedOptionModule [ "services" "xserver" "displayManager" "desktopManagerHandlesLidAndPower" ])
+   (mkRemovedOptionModule [ "services" "xserver" "displayManager" "desktopManagerHandlesLidAndPower" ]
+     "The option is no longer necessary because all display managers have already delegated lid management to systemd.")
   ];
 
 }

nixos/modules/system/boot/loader/grub/grub.nix

@@ -500,7 +500,7 @@ in
 
 
   imports =
-    [ (mkRemovedOptionModule [ "boot" "loader" "grub" "bootDevice" ])
+    [ (mkRemovedOptionModule [ "boot" "loader" "grub" "bootDevice" ] "")
       (mkRenamedOptionModule [ "boot" "copyKernels" ] [ "boot" "loader" "grub" "copyKernels" ])
       (mkRenamedOptionModule [ "boot" "extraGrubEntries" ] [ "boot" "loader" "grub" "extraEntries" ])
       (mkRenamedOptionModule [ "boot" "extraGrubEntriesBeforeNixos" ] [ "boot" "loader" "grub" "extraEntriesBeforeNixOS" ])