docs: core/config/mailbox_formats/dbox - Document migration away from mailbox_directory_name_legacy

Author: fleischie

data/updates.js

@@ -144,6 +144,7 @@ export const updates = {
 	settings_mail_cache_max_headers_count_added: '2.4.0',
 	settings_mail_cache_max_header_name_length_added: '2.4.0',
 	settings_mail_lua_added: '2.4.0',
+	settings_mailbox_directory_name_legacy_deprecated: '2.4.2',
 	settings_mailbox_special_use_changed: '2.4.0',
 	settings_metric_fields_changed: '2.4.0',
 	settings_passdb_mechanisms_filter_added: '2.4.0',

docs/core/config/mailbox_formats/dbox.md

@@ -12,6 +12,9 @@ dovecotlinks:
   sdbox:
     hash: single-dbox-sdbox
     text: sdbox
+  dbox_migrating_away_from_mailbox_directory_name_legacy:
+    hash: migrating-away-from-mailbox-directory-name-legacy
+    text: "dbox: Migrating away from `mailbox_directory_name_legacy`"
 ---
 
 # dbox Mailbox Format
@@ -287,3 +290,18 @@ mail_path = ~/mdbox
 * [[setting,mailbox_list_layout,fs]],
 * [[setting,mailbox_directory_name,dbox-Mails]], and
 * [[setting,mailbox_root_directory_name,mailboxes]].
+
+### Migrating away from `mailbox_directory_name_legacy`
+
+[[deprecated,settings_mailbox_directory_name_legacy_deprecated]]
+[[setting,mailbox_directory_name_legacy]] setting is deprecated and its default
+value is changed from `true` to `false`. This change requires migrations, though:
+
+* Start with [[setting,mailbox_directory_name_legacy,yes]],
+* for each user run:
+  `doveadm -o mail_home=/var/newmails/$user -o mailbox_directory_name_legacy=no sync -u $user`,
+* shutdown all mail access,
+* for each user run [[man,doveadm-sync]] again,
+* switch the [[setting_text,mail_path,mail directory]],
+* set [[setting,mailbox_directory_name_legacy,no]],
+* start dovecot.