ssh: deprecate the list form of match block

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

1 files changed, 36 insertions, 0 deletions

diff --git a/doc/release-notes/rl-2003.adoc b/doc/release-notes/rl-2003.adoc
index bc94b15ce1c..02014bc234d 100644
--- a/doc/release-notes/rl-2003.adoc
+++ b/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