diff --git a/docs/installation/upgrade/include/2.3-to-2.4.inc b/docs/installation/upgrade/include/2.3-to-2.4.inc
index ace0b2674..802632ccc 100644
--- a/docs/installation/upgrade/include/2.3-to-2.4.inc
+++ b/docs/installation/upgrade/include/2.3-to-2.4.inc
@@ -1,5 +1,25 @@
 ## Dovecot Core
 
+### Configuration Changes
+
+The first setting in `dovecot.conf` must now be
+[[setting,dovecot_config_version]]. This helps to avoid unexpected
+configuration changes in the future.
+
+passdb and userdb sections now require a name, i.e.:
+
+
+```
+# This gives an error:
+passdb {
+  ...
+}
+
+# Use this instead:
+passdb some_name {
+}
+```
+
 ### Removed Features
 
 | Feature | Notes |