Document new_mode server variable

server/ha-and-performance/optimization-and-tuning/system-variables/server-system-variables.md

@@ -1818,6 +1818,17 @@ This setting removes the artificial cap, allowing `max_connections` to scale per
 * Default Value: `60`
 * Range: `1` upwards
 
+#### `new_mode`
+
+* Description: Used to enable new behavior in otherwise stable versions. See [NEW Mode](../../../server-management/variables-and-modes/new-mode.md). Non-default NEW\_MODE options are by design deprecated and will eventually be removed.
+* Command line: `--new-mode`
+* Scope: Global, Session
+* Dynamic: Yes
+* Data Type: `string`
+* Default Value: `(empty string)`
+* Valid Values: See [NEW Mode](../../../server-management/variables-and-modes/new-mode.md) for the full list.
+
+
 #### `note_verbosity`
 
 * Description: Verbosity level for note-warnings given to the user. Options are added in a comma-delimited string, except for `all`, which sets all options. Be aware that if the old [sql\_notes](server-system-variables.md#sql_notes) variable is 0, one will not get any notes. Setting `note_verbosity` to "" is the recommended way to disable notes.

server/server-management/starting-and-stopping-mariadb/mariadbd-options.md

@@ -95,6 +95,7 @@ other MariaDB and MySQL versions. Options that are also system variables are lis
 
 ### Compatibility Options and System Variables
 
+* [--new-mode](../../ha-and-performance/optimization-and-tuning/system-variables/server-system-variables.md#new_mode)
 * [--old](../../ha-and-performance/optimization-and-tuning/system-variables/server-system-variables.md#old)
 * [--old-alter-table](../../ha-and-performance/optimization-and-tuning/system-variables/server-system-variables.md#old_alter_table)
 * [--old-mode](../../ha-and-performance/optimization-and-tuning/system-variables/server-system-variables.md#old_mode)

server/server-management/variables-and-modes/new_mode.md

@@ -0,0 +1,45 @@
+# NEW\_MODE
+
+The `NEW_MODE` system variable and command line switch were introduced in [MariaDB 11.4](https://mariadb.com/docs/release-notes/community-server/mariadb-11-4-series/what-is-mariadb-114) to provide a way to enable new behavior in otherwise stable versions. Specifying a flag in the `NEW_MODE` variable enables the corresponding new behavior; otherwise, the old (stable) behavior is used. This can be useful to preserve execution plans in stable versions that may change when the new behavior is active.
+
+A sample usage scenario is:
+
+* a fix (new behavior) is pushed into stable releases (for example, MariaDB 11.4 and MariaDB 11.8). It becomes available in `NEW_MODE` but isn't enabled by default.
+* in MariaDB 12.1, the fix (new behavior) is enabled without the switch. There's no way to turn it off.
+ * `NEW_MODE` does not list the fix as something that can be turned on.
+ * if you specify `fix_X` that is no longer switchable, a warning is printed. However, if you specify `fix_that_never_existed`, an error is produced.
+
+## Syntax
+
+You can set `NEW_MODE` from the [command line](../starting-and-stopping-mariadb/mariadbd-options.md) using the `--new-mode` option, or by setting the [new\_mode](../../ha-and-performance/optimization-and-tuning/system-variables/server-system-variables.md#new_mode) system variable.
+
+```sql
+SET [GLOBAL|SESSION] new_mode = 'fix_1[,fix_2]...';
+```
+
+The session value only affects the current client and can be changed by the client when required. Setting the global value requires the SUPER privilege, and the change will affect any clients that connect from that point forward.
+
+### Example
+
+```sql
+SET GLOBAL new_mode = 'FIX_DISK_TMPTABLE_COSTS';
+...
+SET new_mode = 'FIX_DISK_TMPTABLE_COSTS,FIX_INDEX_STATS_FOR_ALL_NULLS';
+...
+SET SESSION new_mode = 'FIX_INDEX_STATS_FOR_ALL_NULLS';
+
+SET new_mode = '';
+```
+
+## Available NEW_MODE Flags
+
+1. `FIX_DISK_TMPTABLE_COSTS`
+2. `FIX_INDEX_STATS_FOR_ALL_NULLS`
+
+### FIX_DISK_TMPTABLE_COSTS
+
+This flag improves the cost computation for using temporary tables in certain cases, including semi-join subquery materialization ([MDEV-37723](https://jira.mariadb.org/browse/MDEV-37723)).
+
+### FIX_INDEX_STATS_FOR_ALL_NULLS
+
+This flag improves the selection of execution plans when indexed columns contain only NULL values ([MDEV-36761](https://jira.mariadb.org/browse/MDEV-36761)).