From 402106559ec30c63f2198a5a6cf2b9cd2550d2ec Mon Sep 17 00:00:00 2001 From: Ross Patterson Date: Sun, 17 Aug 2025 08:20:33 -0700 Subject: [PATCH] docs(config): Clarify preset ordering priority Refs #1276 --- docs/source/config_reference/config_yaml.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/source/config_reference/config_yaml.rst b/docs/source/config_reference/config_yaml.rst index 8e4097c3..94233766 100644 --- a/docs/source/config_reference/config_yaml.rst +++ b/docs/source/config_reference/config_yaml.rst @@ -82,9 +82,18 @@ Presets also support inheritance from multiple presets: - "custom_preset" - "parent_preset" -In this example, ``child_preset`` will inherit all fields from ``custom_preset`` -and ``parent_preset`` in that order. The bottom-most preset has the highest -priority. +In this example, ``child_preset`` will inherit all fields from ``custom_preset`` and +``parent_preset`` in that order. The bottom-most preset has the highest priority. More +specifically, presets are merged using `mergedeep`_ via `a TYPESAFE_ADDITIVE merge`_, +which means: + +- if two conflicting keys arent lists or mappings, overwrite the higher priority one +- otherwise, combine then re-evaluate If you are only inheriting from one preset, the syntax ``preset: "parent_preset"`` is -valid YAML. Inheriting from multiple presets require use of a list. \ No newline at end of file +valid YAML. Inheriting from multiple presets require use of a list. + +.. _`mergedeep`: + https://mergedeep.readthedocs.io/en/latest/ +.. _`a TYPESAFE_ADDITIVE merge`: + https://mergedeep.readthedocs.io/en/latest/index.html#merge-strategies