docs: rewrite 26.05 release notes

.rstcheck.cfg

@@ -0,0 +1,2 @@
+[rstcheck]
+ignore_messages = Hyperlink target ".*" is not referenced.

docs/dkim.rst

@@ -1,3 +1,5 @@
+.. _dkim:
+
 DKIM Signing
 ============
 
@@ -54,6 +56,8 @@ if set) based on :option:`mailserver.dkim.defaults
   .. _25.11 release: release-notes.html#nixos-25-11
   .. _RFC8301 3.2: https://www.rfc-editor.org/rfc/rfc8301#section-3.2
 
+.. _dkim-key-rotation:
+
 DKIM Key Rotation
 ~~~~~~~~~~~~~~~~~
 

docs/ldap.rst

@@ -1,3 +1,5 @@
+.. _ldap-top:
+
 LDAP
 ====
 

docs/migrations.rst

@@ -13,6 +13,8 @@ apply to your setup.
 NixOS 26.05
 -----------
 
+.. _migration-5:
+
 #5 Sieve script directory migration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -94,6 +96,8 @@ This migration is only required if you have :option:`mailserver.enableManageSiev
 10. If you temporarily disabled :option:`mailserver.enableManageSieve` in step 1,
     re-enable it now by setting it back to ``true``.
 
+.. _migration-4:
+
 #4 Dovecot LDAP UUID-based home directories
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/release-notes.rst

@@ -4,62 +4,90 @@ Release Notes
 NixOS 26.05
 -----------
 
-- Certificate handling was simplified.  We recommend setting
+Features
-  :option:`mailserver.x509.useACMEHost` to a ``security.acme.certs``
+^^^^^^^^
-  configuration. If that does not fit your requirements, configure certificate
+
-  and private key using :option:`mailserver.x509.certificateFile` and
+- :ref:`DKIM key management <dkim>` now supports multiple selectors per domain,
-  :option:`mailserver.x509.privateKeyFile` instead. Support for automatic
+  enabling :ref:`key rotation <dkim-key-rotation>`. Pre-created key material is
-  creation of self-signed certificates has been removed.
+  also supported. Existing automatically generated DKIM keys from before 25.11
-  Check the updated `setup guide`_ for a basic ACME HTTP-01 example.
+  use 1024-bit RSA and should be rotated. See :option:`mailserver.dkim.domains`.
-- `DKIM key management`_ is now available with multiple concurrent selectors per
+
-  domain enabling proper DKIM key rotation. While we still generate a default
+- Certificate handling was simplified. We recommend using the NixOS
-  key for backwards compatibility we now also support passing pre-created
+  ACME module (``security.acme.certs``) and referencing a certificate
-  key material. If your DKIM keys were automatically created before the 25.11
+  configuration by name. Alternatively, certificate and private key can be
-  release they are 1024 bit RSA keys and should be rotated out.
+  managed manually. Configure either :option:`mailserver.x509.useACMEHost`
-  See :option:`mailserver.dkim.domains` for further relevant options.
+  or :option:`mailserver.x509.certificateFile` and
-- Cleartext password files can now be configured for login accounts. This
+  :option:`mailserver.x509.privateKeyFile`. See the updated :ref:`setup guide
-  is an alternative to hashed passwords that integrates well with workflows
+  <setup-guide>` for a basic ACME HTTP-01 example.
-  established by `agenix`_/`sops-nix`_ that instead rely on encryption. This
+
-  option prevents files from leaking in to the Nix store.
+- Local mail accounts can now use managed cleartext passwords. This integrates
-  See :option:`mailserver.accounts.<name>.passwordFile`.
+  well with secret management tools such as `agenix`_ and `sops-nix`_ while
-- TLS configurations have been updated:
+  avoiding password leakage into the world-readable Nix store. See
+  :option:`mailserver.accounts.<name>.passwordFile`.
+
+- Blocked sender responses can now be customized. This is useful if you require GDPR
+  compliance. See :option:`mailserver.rejectSenderMessage`.
+
+Security
+^^^^^^^^
 
 - TLSv1.2 cipher suites in Postfix now require `AEAD`_ and `ECDHE`_.
-  - Postfix and Dovecot allow for the ``SecP256r1MLKEM768``
-    key exchange, as specified in the ongoing
-    `standardization effort <https://datatracker.ietf.org/doc/draft-ietf-tls-ecdhe-mlkem/>`__.
-  - Postfix no longer supports uncommon, deprecated, and obsolete TLS signature
-    algorithms.
 
-- LDAP setups require a migration of Dovecot home directories to
+- Postfix and Dovecot now support negotiation of the ``SecP256r1MLKEM768``
-  `UUID based home directories`_. The exact UUID attribute can be customized
+  key agreement mechanism. The `standardization process
-  through :option:`mailserver.ldap.attributes.uuid`.
+  <https://datatracker.ietf.org/doc/draft-ietf-tls-ecdhe-mlkem/>`__ is ongoing.
-- The default login username for LDAP users has changed from the ``mail`` to
+
-  the ``uid`` attribute. This allows users to login with their account name
+- Deprecated and obsolete TLS signature algorithms were removed from Postfix.
-  rather than their email address, which is more convenient and consistent
+
-  with typical LDAP practices. The exact attribute can be customized through
+Sieve
+^^^^^
+
+- **Migration**: When ManageSieve is enabled, user-created Sieve scripts must
+  be migrated into their Dovecot home directory. See the :ref:`migration guide
+  <migration-5>`.
+
+LDAP
+^^^^
+
+- **Migration**: Dovecot home directories for LDAP users must be migrated to
+  UUID-based directory names. The UUID attribute can be customized through
+  :option:`mailserver.ldap.attributes.uuid`. See the :ref:`migration guide
+  <migration-4>`.
+
+- The LDAP configuration has been revamped. Option names have been simplified,
+  examples and documentation improved. The :ref:`LDAP documentation <ldap-top>`
+  was written from the ground up.
+
+- The default LDAP login attribute changed from ``mail`` to ``uid``.
+  This allows users to login with their account name rather than
+  their email address, which is more convenient and consistent with
+  typical LDAP practices. The exact attribute can be customized through
   :option:`mailserver.ldap.attributes.username`.
-- Local and LDAP accounts can now co-exist. For overlapping names and addresses
+
+- Local and LDAP accounts can now coexist. For overlapping accounts and addresses
   the local account will always win.
-- Custom reject messages for blocked senders are now possible by setting
+
-  :option:`mailserver.rejectSenderMessage` to e.g. comply with GDPR.
+
-- The following integrations are deprecated and will be removed before the next
+Internals
+^^^^^^^^^
+
+- Dovecot has been updated from 2.3 to 2.4 and now relies on the structured settings option.
+
+Deprecations
+^^^^^^^^^^^^
+
+The following integrations are deprecated and will be removed before the next
 release:
 
 - :option:`mailserver.borgbackup.enable`
 - :option:`mailserver.backup.enable`
 - :option:`mailserver.monitoring.enable`
-- Setups with :option:`mailserver.enableManageSieve` enabled require a
-  migration of the `Sieve script directories into Dovecot home directories`_.
 
-.. _setup guide: setup-guide.html#setup-the-server
+.. _key rotation: dkim.html#dkim-key-rotation
-.. _DKIM key management: dkim.html
 .. _agenix: https://github.com/ryantm/agenix
 .. _sops-nix: https://github.com/Mic92/sops-nix
 .. _AEAD: https://en.wikipedia.org/wiki/Authenticated_encryption
 .. _ECDHE: https://www.rfc-editor.org/rfc/rfc8422
-.. _UUID based home directories: migrations.html#dovecot-ldap-uuid-based-home-directories
-.. _Sieve script directories into Dovecot home directories: migrations.html#sieve-script-directory-migration
 
 NixOS 25.11
 -----------

docs/setup-guide.rst

@@ -1,3 +1,5 @@
+.. _setup-guide:
+
 Setup Guide
 ===========