USE_FOLDERS: Treat as on by default

Add a policy to treat the `USE_FOLDERS` global property as ON by default
if it is not set.

Fixes: #21695

1 files changed, 30 insertions, 0 deletions

diff --git a/Help/policy/CMP0143.rst b/Help/policy/CMP0143.rst
new file mode 100644
index 0000000..7a7aee7
--- /dev/null
+++ b/Help/policy/CMP0143.rst
@@ -0,0 +1,30 @@
+CMP0143
+-------
+
+.. versionadded:: 3.26
+
+:prop_gbl:`USE_FOLDERS` global property is treated as ``ON`` by default.
+
+When using CMake 3.25 and below, :prop_gbl:`USE_FOLDERS` is treated
+as ``OFF`` by default unless projects enable the feature.  For example:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.25)
+  project(foobar LANGUAGES CXX)
+  set_property(GLOBAL PROPERTY USE_FOLDERS ON)
+
+CMake 3.26 and later prefer to enable the feature by default.
+
+This policy provides compatibility with projects that have not been updated
+to expect enabling of folders.  Enabling folders causes projects to appear
+differently in IDEs.
+
+This policy was introduced in CMake version 3.26.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+The policy setting must be in scope at the end of the top-level
+``CMakeLists.txt`` file of the project and has global effect.
+
+.. include:: DEPRECATED.txt