execute_process: Change default ENCODING to UTF-8

Windows is heading toward making UTF-8 the preferred MBCS.  As CMake's
internal encoding, `UTF-8` is effectively equivalent to `NONE`, which
was CMake's behavior prior to 3.15's accidental change to `AUTO`.
Behavior of `ENCODING UTF-8` is independent of CMake's internal
encoding, making it in principle a better default than `NONE`.

Add policy CMP0176 for compatibility and to document the default's
history.

Fixes: #26262

1 files changed, 27 insertions, 0 deletions

diff --git a/Help/policy/CMP0176.rst b/Help/policy/CMP0176.rst
new file mode 100644
index 0000000..4683174
--- /dev/null
+++ b/Help/policy/CMP0176.rst
@@ -0,0 +1,27 @@
+CMP0176
+-------
+
+.. versionadded:: 3.31
+
+:command:`execute_process` ``ENCODING`` is ``UTF-8`` by default.
+
+The ``ENCODING`` option is meaningful only on Windows.  It specifies the
+character encoding expected in the process's output on stdout and stderr.
+In CMake 3.14 and below the default encoding was ``NONE``, which corresponds
+to CMake's internal UTF-8 encoding.  In CMake 3.15 through CMake 3.30 the
+default encoding was accidentally changed to ``AUTO``, but the change went
+unnoticed and was not documented.
+
+CMake 3.31 and above prefer the ``ENCODING`` default to be ``UTF-8``.
+This policy provides compatibility with projects that may have been
+relying on the default being ``AUTO``.
+
+The ``OLD`` behavior of this policy is for :command:`execute_process`
+to use ``AUTO`` by default if no ``ENCODING`` is specified.  The ``NEW``
+behavior for this policy is to use ``UTF-8`` as the default ``ENCODING``.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt