Update top file merging docs to reflect new strategy

doc/ref/configuration/minion.rst

@@ -1218,12 +1218,15 @@ This option has no default value. Set it to an environment name to ensure that
 
 .. note::
     Using this value does not change the merging strategy. For instance, if
-    :conf_minion:`top_file_merging_strategy` is left at its default, and
+    :conf_minion:`top_file_merging_strategy` is set to ``default``, and
     :conf_minion:`state_top_saltenv` is set to ``foo``, then any sections for
     environments other than ``foo`` in the top file for the ``foo`` environment
     will be ignored. With :conf_minion:`top_file_merging_strategy` set to
     ``base``, all states from all environments in the ``base`` top file will
-    be applied, while all other top files are ignored.
+    be applied, while all other top files are ignored. The only way to set
+    :conf_minion:`state_top_saltenv` to something other than ``base`` and not
+    have the other environments in the targeted top file ignored, would be to
+    set :conf_minion:`top_file_merging_strategy` to ``merge_all``.
 
 .. code-block:: yaml
 
@@ -1234,19 +1237,29 @@ This option has no default value. Set it to an environment name to ensure that
 ``top_file_merging_strategy``
 -----------------------------
 
-Default: ``merge``
+.. versionchanged:: Carbon
+    Default value has been changed from ``merge`` to ``default`` to reflect the
+    fact that states from matching targets in matching environments in multiple
+    top files are not actually being merged. Additonally, the ``merge_all``
+    strategy has been added.
+
+Default: ``default``
 
 When no specific fileserver environment (a.k.a. ``saltenv``) has been specified
 for a :ref:`highstate <running-highstate>`, all environments' top files are
 inspected. This config option determines how the SLS targets in those top files
 are handled.
 
-When set to the default value of ``merge``, all SLS files are interpreted. The
-first target expression for a given environment is kept, and when the same
+When set to ``default``, the ``base`` environment's top file is evaluated
+first, followed by the other environments' top files. The first target
+expression (e.g. ``'*'``) for a given environment is kept, and when the same
 target expression is used in a different top file evaluated later, it is
-ignored. The environments will be evaluated in no specific order, for greater
-control over the order in which the environments are evaluated use
-:conf_minion:`env_order`.
+ignored. Because ``base`` is evaluated first, it is authoritative. For
+example, if there is a target for ``'*'`` for the ``foo`` environment in both
+the ``base`` and ``foo`` environment's top files, the one in the ``foo``
+environment would be ignored. The environments will be evaluated in no specific
+order (aside from ``base`` coming first). For greater control over the order in
+which the environments are evaluated, use :conf_minion:`env_order`.
 
 When set to ``same``, then for each environment, only that environment's top
 file is processed, with the others being ignored. For example, only the ``dev``
@@ -1256,6 +1269,12 @@ environment's) top file will be ignored. If an environment does not have a top
 file, then the top file from the :conf_minion:`default_top` config parameter
 will be used as a fallback.
 
+When set to ``merge_all``, then all states in all environments in all top files
+will be applied. The order in which individual SLS files will be executed will
+depend on the order in which the top files were evaluated, and the environments
+will be evaluated in no specific order. For greater control over the order in
+which the environments are evaluated, use :conf_minion:`env_order`.
+
 .. code-block:: yaml
 
     top_file_merging_strategy: same
@@ -1287,9 +1306,10 @@ explicitly defined.
 Default: ``base``
 
 When :conf_minion:`top_file_merging_strategy` is set to ``same``, and no
-environment is specified for a :ref:`highstate <running-highstate>`, this
-config option specifies a fallback environment in which to look for a top file
-if an environment lacks one.
+environment is specified for a :ref:`highstate <running-highstate>` (i.e.
+:conf_minion:`environment` is not set for the minion), this config option
+specifies a fallback environment in which to look for a top file if an
+environment lacks one.
 
 .. code-block:: yaml
 

doc/ref/states/top.rst

@@ -354,7 +354,8 @@ used, a single top file in the ``base`` environment is the most common way of
 configuring a :ref:`highstate <running-highstate>`.
 
 The following minion configuration options affect how top files are compiled
-when no environment is specified:
+when no environment is specified, it is recommended to follow the below four
+links to learn more about how these options work:
 
 - :conf_minion:`state_top_saltenv`
 - :conf_minion:`top_file_merging_strategy`
@@ -404,6 +405,7 @@ For the scenarios below, assume the following configuration:
         - dev2
     qa:
       '*':
+        - qa1
         - qa2
 
 .. note::
@@ -426,8 +428,8 @@ If the ``base`` environment were specified, the result would be that only the
 If the ``qa`` environment were specified, the :ref:`highstate
 <running-highstate>` would exit with an error.
 
-Scenario 2 - No Environment Specified, :conf_minion:`top_file_merging_strategy` is "merge"
-------------------------------------------------------------------------------------------
+Scenario 2 - No Environment Specified, :conf_minion:`top_file_merging_strategy` is "default"
+--------------------------------------------------------------------------------------------
 
 .. versionchanged:: Carbon
     The default merging strategy has been renamed from ``merge`` to
@@ -458,5 +460,18 @@ minion2.
 
 If :conf_minion:`default_top` is unset (or set to ``base``, which happens to be
 the default), then ``qa1`` from the ``qa`` environment will be applied to all
-minions. If :conf_minion:`default_top` were set to ``dev``, then ``qa2`` from
-the ``qa`` environment would be applied to all minions.
+minions. If :conf_minion:`default_top` were set to ``dev``, then both ``qa1``
+and ``qa2`` from the ``qa`` environment would be applied to all minions.
+
+Scenario 3 - No Environment Specified, :conf_minion:`top_file_merging_strategy` is "merge_all"
+----------------------------------------------------------------------------------------------
+
+.. versionadded:: Carbon
+
+In this scenario, all configured states in all top files are applied. From the
+``base`` environment, ``base1`` would be applied to all minions, with ``base2``
+being applied only to ``minion1``. From the ``dev`` environment, ``dev1`` would
+be applied to all minions, with ``dev2`` being applied only to ``minion2``.
+Finally, from the ``qa`` environment, both the ``qa1`` and ``qa2`` states will
+be applied to all minions. Note that the ``qa1`` states would not be applied
+twice, even though ``qa1`` appears twice.