merge_all for top files ---> obsoletes quite a bit of documentation?

[Trever Nightingale]

Hi,

I am wondering:  with the addition of merge_all for top files (added 2016.11.0 which is not that long ago), does that mean a lot of old documentation and advice that I'm seeing is not applicable because out of date?  A relevant link is: https://docs.saltstack.com/en/latest/ref/configuration/minion.html#top-file-merging-strategy

Specifically, I wonder if what is now merge_all used to be the default behavior, but now it's merge, which gives many of us what is desired behavior?  If true, this would explain a lot of old advice and documentation and explain why it is no longer applicable- if I'm understanding things.  But I want to know if I'm understanding things.

Thus, when it says in gitfs doc (https://docs.saltstack.com/en/latest/topics/tutorials/gitfs.html):

"Branching and tagging can result in a lot of potentially-conflicting top files, for this reason it may be useful to set top_file_merging_strategy to same in the minions' config files if the top files are being managed in a GitFS repo."    

This caution and advice seems to be no longer true, at least not by default. Merge is the default now, and that entails that "aside from the base environment's top file, any sections in top files that do not match that top file's environment will be ignored. So, for example, a section for the qa environment would be ignored if it appears in the dev environment's top file".  In other words, as I read this, you don't presumably get conflicting top files.  They can conflict but the conflicts are ignored unless you use merge_all.

Likewise, other doc says (https://docs.saltstack.com/en/latest/ref/states/top.html#how-top-files-are-compiled):  "By default, the top files from each environment will be merged together. In configurations with many environments, such as with GitFS where each branch and tag is treated as a distinct environment, this may cause unexpected results as SLS files from older tags cause defunct SLS files to be included in the highstate. In cases like this, it can be helpful to set top_file_merging_strategy to same to force each environment to use its own top file."  This also seems no longer true.  It seems that now, "same" is just used if you don't want base to take precedence over all other environment top files, but apart from base, there is no environment merging of top files.  (But it seems to me, the default is now sane- that having base take precedence will work fine for us.)

I'm on the hook to update some other salt proejct doc and can update these docs too, if what I'm wondering about here is correct.

Thanks all,

Trever