cmake_minimum_required version bump timing after CMake binary upgrade

Short answer

Bump cmake_minimum_required only when the policy floor — not the binary — is what blocks you. Upgrading the CMake executable changes nothing about project behavior on its own: the directive pins every policy introduced up to that version to NEW, and policies from later releases default to OLD with warnings. The binary upgrade and the minimum-version bump are two independent decisions, and conflating them is the most common mistake here.

Criteria that justify the bump

• You need a feature or NEW-policy behavior that only exists above your current floor (e.g., CMP0077 making option() honor normal variables), and per-policy opt-ins have become unwieldy.
• Configure output warns that your current minimum is deprecated and will stop being supported, making the bump eventually mandatory.
• Your CI matrix and developer environments already standardize on a newer binary, so the old floor no longer buys real compatibility — it only suppresses warnings.

If none of these hold, keep the floor low. A lower minimum widens who can build from source.

Verifying that policy flips don't change the build

Before committing the bump, trial the risky policies individually with cmake_policy(SET CMPxxxx NEW) — this isolates behavior changes one at a time instead of flipping a dozen at once. Then verify the full bump empirically:

# See which policies your current minimum leaves unset
cmake --help-policy-list

# Configure old vs new minimum into separate fresh build dirs
cmake -S . -B build-old   # current minimum
cmake -S . -B build-new   # bumped minimum
diff build-old/CMakeCache.txt build-new/CMakeCache.txt
diff build-old/compile_commands.json build-new/compile_commands.json

Grep the configure log for Policy CMP warnings — each one names an exact behavior flip to audit. Finally, run the full CTest suite in both trees and compare results. Always reconfigure in a fresh build directory; a stale CMakeCache.txt from the old binary can fail in confusing ways that have nothing to do with the version bump.

Staging across release branches

The documented escape hatch is the version-range form:

cmake_minimum_required(VERSION 3.16...3.27)

This keeps old binaries able to configure while opting into NEW policies up to the upper bound when a newer binary runs — ideal for a transition period. A practical rollout: bump the floor on the development branch first, leave long-lived release branches on the old minimum until end-of-life, and state the new floor prominently in release notes, since it is a breaking change for anyone building from source with an older CMake.

Caveats

Exact policy numbers, deprecation schedules, and the lowest still-supported minimum vary by CMake release — confirm against your installed version's own cmake --help-policy output. Also audit vendored third-party scripts before bumping: they may silently rely on OLD behavior, and mechanisms like CMAKE_POLICY_DEFAULT_CMPxxxx can change them without any warning in your own code.