ssh: deprecate the list form of match block

Configurations depending on specific block order should use the DAG
functions instead of lists.

doc/release-notes/rl-2003.adoc

@@ -74,6 +74,42 @@ new module `services.picom` should be used. This is because Nixpkgs no
 longer packages compton, and instead packages the (mostly) compatible
 fork called picom.
 
+* The list form of the <<opt-programs.ssh.matchBlocks>> option has
+been deprecated and configurations requiring match blocks in a defined
+order should switch to using DAG entries instead. For example, a
+configuration
++
+[source,nix]
+----
+programs.ssh.matchBlocks = [
+  {
+    host = "alpha.foo.com";
+    user = "jd";
+  }
+  {
+    host = "*.foo.com";
+    user = "john.doe";
+  }
+];
+----
++
+can be expressed along the lines of
++
+[source,nix]
+----
+programs.ssh.matchBlocks = {
+  "*.example.com" = {
+    user = "john.doe";
+  }
+  "alpha.example.com" = lib.hm.dag.entryBefore ["*.example.com"] {
+    user = "jd";
+  }
+};
+----
++
+Support for the list form will be removed in Home Manager version
+20.09.
+
 [[sec-release-20.03-state-version-changes]]
 === State Version Changes
 

modules/lib/types-dag.nix

@@ -60,27 +60,37 @@ in rec {
         let padWidth = stringLength (toString (length list));
         in fixedWidthNumber padWidth i;
 
-      convertAll = defs:
+      convertAll = loc: defs:
         let
-          convertListValue = namePrefix: vs:
+          convertListValue = namePrefix: def:
             let
+              vs = def.value;
               pad = paddedIndexStr vs;
               makeEntry = i: v: nameValuePair "${namePrefix}.${pad i}" v;
-            in listToAttrs (imap1 makeEntry vs);
+              warning = ''
+                In file ${def.file}
+                a list is being assigned to the option '${
+                  concatStringsSep "." loc
+                }'.
+                This will soon be an error due to the list form being deprecated.
+                Please use the attribute set form instead with DAG functions to
+                express the desired order of entries.
+              '';
+            in warn warning (listToAttrs (imap1 makeEntry vs));
 
-          convertValue = i: value:
+          convertValue = i: def:
-            if isList value then
+            if isList def.value then
-              convertListValue "unnamed-${paddedIndexStr defs i}" value
+              convertListValue "unnamed-${paddedIndexStr defs i}" def
             else
-              value;
+              def.value;
-        in imap1 (i: def: def // { value = convertValue i def.value; }) defs;
+        in imap1 (i: def: def // { value = convertValue i def; }) defs;
 
       dagType = dagOf elemType;
     in mkOptionType rec {
       name = "listOrDagOf";
       description = "list or DAG of ${elemType.description}s";
       check = x: isList x || dagType.check x;
-      merge = loc: defs: dagType.merge loc (convertAll defs);
+      merge = loc: defs: dagType.merge loc (convertAll loc defs);
       getSubOptions = dagType.getSubOptions;
       getSubModules = dagType.getSubModules;
       substSubModules = m: listOrDagOf (elemType.substSubModules m);