nixos/manual: document kernel backporting policy and implications of it

I'm well aware that this issue is currently under discussion[1] and that
these things may change. Also, please don't misinterpret this as an
attempt to end the discussion.

This topic made it obvious that people are surprised by the way this
issue is handled and only finding out about this unwritten rule because
of asking is not a good state IMHO, so I decided to document the
following things:

* Right now we drop kernels as soon as they get out of maintenance (LTS
  kernels even before the next stable NixOS that will exceed their
  lifespan).
* The `latestCompatibleLinuxPackages` attribute from ZFS isn't
  monotonic since latest only refers to the latest supported kernel.
* In fact `latestCompatibleLinuxPackages` doesn't seem to be documented
  at all in the manual, so I also did that.

[1] https://discourse.nixos.org/t/aggressive-kernel-removal-on-eol-in-nixos/23097

2 files changed, 71 insertions, 0 deletions

diff --git a/nixos/doc/manual/configuration/linux-kernel.chapter.md b/nixos/doc/manual/configuration/linux-kernel.chapter.md
index 1d06543d4f1..87c1cf6a7cb 100644
--- a/nixos/doc/manual/configuration/linux-kernel.chapter.md
+++ b/nixos/doc/manual/configuration/linux-kernel.chapter.md
@@ -17,6 +17,16 @@ you may want to use one of the unversioned `pkgs.linuxPackages_*` aliases
 such as `pkgs.linuxPackages_latest`, that are kept up to date with new
 versions.
 
+Please note that the current convention in NixOS is to only keep actively
+maintained kernel versions on both unstable and the currently supported stable
+release(s) of NixOS. This means that a non-longterm kernel will be removed after it's
+abandoned by the kernel developers, even on stable NixOS versions. If you
+pin your kernel onto a non-longterm version, expect your evaluation to fail as
+soon as the version is out of maintenance.
+
+Longterm versions of kernels will be removed before the next stable NixOS that will
+exceed the maintenance period of the kernel version.
+
 The default Linux kernel configuration should be fine for most users.
 You can see the configuration of your current kernel with the following
 command:
@@ -138,3 +148,23 @@ $ cd linux-*
 $ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
 # insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
 ```
+
+## ZFS {#sec-linux-zfs}
+
+It's a common issue that the latest stable version of ZFS doesn't support the latest
+available Linux kernel. It's possible to pin the system to the latest available kernel
+version *that is supported by ZFS* like this:
+
+```nix
+{
+  boot.kernelPackages = pkgs.zfs.latestCompatibleLinuxPackages;
+}
+```
+
+Please note that the version this attribute points to isn't monotonic because the latest kernel
+version only refers to kernel versions supported by the Linux developers. In other words,
+the latest kernel version that ZFS is compatible with may decrease over time.
+
+An example: the latest version ZFS is compatible with is 5.19 which is a non-longterm version. When 5.19
+is out of maintenance, the latest supported kernel version is 5.15 because it's longterm and the versions
+5.16, 5.17 and 5.18 are already out of maintenance because they're non-longterm.
diff --git a/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml
index a1d6815af29..7fb3ba5ac98 100644
--- a/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml
+++ b/nixos/doc/manual/from_md/configuration/linux-kernel.chapter.xml
@@ -22,6 +22,19 @@ boot.kernelPackages = pkgs.linuxKernel.packages.linux_3_10;
     date with new versions.
   </para>
   <para>
+    Please note that the current convention in NixOS is to only keep
+    actively maintained kernel versions on both unstable and the
+    currently supported stable release(s) of NixOS. This means that a
+    non-longterm kernel will be removed after it’s abandoned by the
+    kernel developers, even on stable NixOS versions. If you pin your
+    kernel onto a non-longterm version, expect your evaluation to fail
+    as soon as the version is out of maintenance.
+  </para>
+  <para>
+    Longterm versions of kernels will be removed before the next stable
+    NixOS that will exceed the maintenance period of the kernel version.
+  </para>
+  <para>
     The default Linux kernel configuration should be fine for most
     users. You can see the configuration of your current kernel with the
     following command:
@@ -154,4 +167,32 @@ $ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox module
 # insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
 </programlisting>
   </section>
+  <section xml:id="sec-linux-zfs">
+    <title>ZFS</title>
+    <para>
+      It’s a common issue that the latest stable version of ZFS doesn’t
+      support the latest available Linux kernel. It’s possible to pin
+      the system to the latest available kernel version <emphasis>that
+      is supported by ZFS</emphasis> like this:
+    </para>
+    <programlisting language="bash">
+{
+  boot.kernelPackages = pkgs.zfs.latestCompatibleLinuxPackages;
+}
+</programlisting>
+    <para>
+      Please note that the version this attribute points to isn’t
+      monotonic because the latest kernel version only refers to kernel
+      versions supported by the Linux developers. In other words, the
+      latest kernel version that ZFS is compatible with may decrease
+      over time.
+    </para>
+    <para>
+      An example: the latest version ZFS is compatible with is 5.19
+      which is a non-longterm version. When 5.19 is out of maintenance,
+      the latest supported kernel version is 5.15 because it’s longterm
+      and the versions 5.16, 5.17 and 5.18 are already out of
+      maintenance because they’re non-longterm.
+    </para>
+  </section>
 </chapter>