FindGDAL: Document as deprecated in favor of upstream CMake package

Issue: #26471

Help/release/dev/FindGDAL-deprecate.rst

@@ -0,0 +1,8 @@
+FindGDAL-deprecate
+------------------
+
+* The :module:`FindGDAL` module is now deprecated in favor of upstream
+  GDAL's official CMake package configuration file. Port projects to
+  the latter by calling ``find_package(GDAL CONFIG)``.  For further
+  details, see `GDAL's documentation on CMake integration
+  <https://gdal.org/en/latest/development/cmake.html>`_.

Modules/FindGDAL.cmake

@@ -7,6 +7,12 @@ FindGDAL
 
 Find Geospatial Data Abstraction Library (GDAL).
 
+.. deprecated:: 3.32
+  GDAL 3.5 and above provide a ``GDALConfig.cmake`` package configuration file.
+  Call ``find_package(GDAL CONFIG)`` to find it directly and avoid using this
+  find module.  For further details, see `GDAL's documentation on CMake
+  integration <https://gdal.org/en/latest/development/cmake.html>`_.
+
 IMPORTED Targets
 ^^^^^^^^^^^^^^^^
 
@@ -184,6 +190,18 @@ else ()
     set(GDAL_VERSION GDAL_VERSION-NOTFOUND)
 endif ()
 
+if (GDAL_FIND_VERSION VERSION_GREATER_EQUAL 3.5)
+   message(DEPRECATION
+     "The FindGDAL module is deprecated.  "
+     "GDAL 3.5 and above provide a CMake package configuration file.  "
+     "Since at least version ${GDAL_FIND_VERSION} is requested, this "
+     "project can be ported to find GDAL's CMake package directly:\n"
+     "  find_package(GDAL CONFIG)\n"
+     "For further details, see:\n"
+     "  https://gdal.org/en/latest/development/cmake.html\n"
+   )
+endif()
+
 include(${CMAKE_CURRENT_LIST_DIR}/FindPackageHandleStandardArgs.cmake)
 FIND_PACKAGE_HANDLE_STANDARD_ARGS(GDAL
     VERSION_VAR GDAL_VERSION