Help: Document policy transition schedule in cmake-policies(7)

Rewrite the introduction of the manual to focus on policies' role in
evolution of CMake and how projects should be updated to account for
them over time.

Issue: #26613

Help/manual/cmake-policies.7.rst

@@ -10,36 +10,71 @@ cmake-policies(7)
 Introduction
 ============
 
-Policies in CMake are used to preserve backward compatible behavior
+CMake policies introduce behavior changes while preserving compatibility
-across multiple releases.  When a new policy is introduced, newer CMake
+for existing project releases.  Policies are deprecation mechanisms, not
-versions will begin to warn about the backward compatible behavior.  It
+feature toggles.  Each policy documents a deprecated ``OLD`` behavior and
-is possible to disable the warning by explicitly requesting the OLD, or
+a preferred ``NEW`` behavior.  Projects must be updated over time to
-backward compatible behavior using the :command:`cmake_policy` command.
+use the ``NEW`` behavior, but their existing releases will continue to
-It is also possible to request ``NEW``, or non-backward compatible behavior
+work with the ``OLD`` behavior.
-for a policy, also avoiding the warning.  Each policy can also be set to
-either ``NEW`` or ``OLD`` behavior explicitly on the command line with the
-:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable.
 
-A policy is a deprecation mechanism and not a reliable feature toggle.
+Updating Projects
-A policy should almost never be set to ``OLD``, except to silence warnings
+-----------------
-in an otherwise frozen or stable codebase, or temporarily as part of a
-larger migration path. The ``OLD`` behavior of each policy is undesirable
-and will be replaced with an error condition in a future release.
 
-The :command:`cmake_minimum_required` command does more than report an
+When policies are newly introduced by a version of CMake, their ``OLD``
-error if a too-old version of CMake is used to build a project.  It
+behaviors are immediately deprecated by that version of CMake and later.
-also sets all policies introduced in that CMake version or earlier to
+Projects should be updated to use the ``NEW`` behaviors of the policies
-``NEW`` behavior.  To manage policies without increasing the minimum required
+as soon as possible.
-CMake version, the :command:`if(POLICY)` command may be used:
 
-.. code-block:: cmake
+Use the :command:`cmake_minimum_required` command to record the latest
+version of CMake for which a project has been updated.
+The ``VERSION <min>...<policy_max>`` syntax enables the ``NEW`` behaviors
+of policies introduced in version ``<policy_max>`` and earlier without
+increasing the minimum version of CMake required by the project.
 
-  if(POLICY CMP0990)
+Transition Schedule
-    cmake_policy(SET CMP0990 NEW)
+-------------------
-  endif()
 
-This has the effect of using the ``NEW`` behavior with newer CMake releases which
+To help projects port to the ``NEW`` behaviors of policies on their own
-users may be using and not issuing a compatibility warning.
+schedule, CMake offers a transition period:
+
+* If a policy is not set by a project, CMake uses its ``OLD`` behavior,
+  but may warn that the policy has not been set.
+
+  * Users running CMake may silence the warning without modifying a
+    project by setting the :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>`
+    variable as a cache entry on the :manual:`cmake(1)` command line:
+
+    .. code-block:: shell
+
+      cmake -DCMAKE_POLICY_DEFAULT_CMP0990=OLD ...
+
+  * Projects may silence the warning by using the :command:`cmake_policy`
+    command to explicitly set the policy to ``OLD`` or ``NEW`` behavior:
+
+    .. code-block:: cmake
+
+      if(POLICY CMP0990)
+        cmake_policy(SET CMP0990 NEW)
+      endif()
+
+    .. note::
+
+      A policy should almost never be set to ``OLD``, except to silence
+      warnings in an otherwise frozen or stable codebase, or temporarily
+      as part of a larger migration path.
+
+* If a policy is set to ``OLD`` by a project, CMake versions released
+  at least |POLICY_OLD_DELAY_WARNING| after the version that introduced
+  a policy may issue a warning that the policy's ``OLD`` behavior will
+  be removed from a future version of CMake.
+
+* If a policy is not set to ``NEW`` by a project, CMake versions released
+  at least |POLICY_OLD_DELAY_ERROR| after the version that introduced a
+  policy, and whose major version number is higher, may issue an error
+  that the policy's ``OLD`` behavior has been removed.
+
+.. |POLICY_OLD_DELAY_WARNING| replace:: 2 years
+.. |POLICY_OLD_DELAY_ERROR| replace:: 6 years
 
 Supported Policies
 ==================