MSVC: Do not add /W3 to CMAKE_<LANG>_FLAGS by default

We do not add default warning flags on other compilers, and having
a warning flag in the default flags makes it hard for projects to
customize the warning level.  They need to use string processing
to remove `/W3` from `CMAKE_{C,CXX}_FLAGS`.  Therefore we should
drop it.

However, projects may be using string processing to replace `/W3`
with another flag, so we cannot simply drop it.  Add a policy to
drop it in a compatible way.

Fixes: #18317

3 files changed, 45 insertions, 0 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 043fb5c..8fcd386 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.15
 .. toctree::
    :maxdepth: 1
 
+   CMP0092: MSVC warning flags are not in CMAKE_{C,CXX}_FLAGS by default. </policy/CMP0092>
    CMP0091: MSVC runtime library flags are selected by an abstraction. </policy/CMP0091>
    CMP0090: export(PACKAGE) does not populate package registry by default. </policy/CMP0090>
    CMP0089: Compiler id for IBM Clang-based XL compilers is now XLClang. </policy/CMP0089>
diff --git a/Help/policy/CMP0092.rst b/Help/policy/CMP0092.rst
new file mode 100644
index 0000000..8d3a288
--- /dev/null
+++ b/Help/policy/CMP0092.rst
@@ -0,0 +1,38 @@
+CMP0092
+-------
+
+MSVC warning flags are not in :variable:`CMAKE_<LANG>_FLAGS` by default.
+
+When using MSVC-like compilers in CMake 3.14 and below, warning flags
+like ``/W3`` are added to :variable:`CMAKE_<LANG>_FLAGS` by default.
+This is problematic for projects that want to choose a different warning
+level programmatically.  In particular, it requires string editing of the
+:variable:`CMAKE_<LANG>_FLAGS` variables with knowledge of the
+CMake builtin defaults so they can be replaced.
+
+CMake 3.15 and above prefer to leave out warning flags from the value of
+:variable:`CMAKE_<LANG>_FLAGS` by default.
+
+This policy provides compatibility with projects that have not been updated
+to expect the lack of warning flags.  The policy setting takes effect as of
+the first :command:`project` or :command:`enable_language` command that
+initializes :variable:`CMAKE_<LANG>_FLAGS` for a given lanuage ``<LANG>``.
+
+.. note::
+
+  Once the policy has taken effect at the top of a project for a given
+  language, that choice must be used throughout the tree for that language.
+  In projects that have nested projects in subdirectories, be sure to
+  convert everything together.
+
+The ``OLD`` behavior for this policy is to place MSVC warning flags in the
+default :variable:`CMAKE_<LANG>_FLAGS` cache entries.  The ``NEW`` behavior
+for this policy is to *not* place MSVC warning flags in the default cache
+entries.
+
+This policy was introduced in CMake version 3.15.  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.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/msvc-warning-flags.rst b/Help/release/dev/msvc-warning-flags.rst
new file mode 100644
index 0000000..b89d6fa
--- /dev/null
+++ b/Help/release/dev/msvc-warning-flags.rst
@@ -0,0 +1,6 @@
+msvc-warning-flags
+------------------
+
+* With MSVC-like compilers the value of :variable:`CMAKE_<LANG>_FLAGS`
+  no longer contains warning flags like ``/W3`` by default.
+  See policy :policy:`CMP0092`.