ExternalProject/FetchContent: Support relative remote URLs

Teach `ExternalProject_Add` and `FetchContent_Declare` to resolve
relative remote URLs provided via `GIT_REPOSITORY`.  Add policy
CMP0150 to maintain compatibility.

Fixes: #24211
Co-Authored-By: Craig Scott <craig.scott@crascit.com>

3 files changed, 47 insertions, 0 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 8c7189a72b..ff573906b2 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.27
 .. toctree::
    :maxdepth: 1
 
+   CMP0150: ExternalProject_Add and FetchContent_Declare treat relative git repository paths as being relative to parent project's remote. </policy/CMP0150>
    CMP0149: Visual Studio generators select latest Windows SDK by default. </policy/CMP0149>
    CMP0148: The FindPythonInterp and FindPythonLibs modules are removed. </policy/CMP0148>
    CMP0147: Visual Studio generators build custom commands in parallel. </policy/CMP0147>
diff --git a/Help/policy/CMP0150.rst b/Help/policy/CMP0150.rst
new file mode 100644
index 0000000000..fe646d98f4
--- /dev/null
+++ b/Help/policy/CMP0150.rst
@@ -0,0 +1,39 @@
+CMP0150
+-------
+
+.. versionadded:: 3.27
+
+:command:`ExternalProject_Add` and :command:`FetchContent_Declare` commands
+treat relative ``GIT_REPOSITORY`` paths as being relative to the parent
+project's remote.
+
+Earlier versions of these commands always treated relative paths in
+``GIT_REPOSITORY`` as local paths, but the base directory it was treated
+as relative to was both undocumented and unintuitive.  The ``OLD`` behavior
+for this policy is to interpret relative paths used for ``GIT_REPOSITORY``
+as local paths relative to the following:
+
+* The parent directory of ``SOURCE_DIR`` for :command:`ExternalProject_Add`.
+* ``FETCHCONTENT_BASE_DIR`` for :command:`FetchContent_Declare`.
+
+The ``NEW`` behavior is to determine the remote from the parent project and
+interpret the path relative to that remote.  The value of
+:variable:`CMAKE_CURRENT_SOURCE_DIR` when :command:`ExternalProject_Add` or
+:command:`FetchContent_Declare` is called determines the parent project.
+The remote is selected according to the following (the first match is used):
+
+* If the parent project is checked out on a branch with an upstream remote
+  defined, use that remote.
+* If only one remote is defined, use that remote.
+* If multiple remotes are defined and one of them is named ``origin``, use
+  ``origin``'s remote but also issue a warning.
+
+If an appropriate remote cannot be determined from the above, a fatal error
+will be raised.
+
+This policy was introduced in CMake version 3.27.  CMake version |release|
+warns when a relative path is encountered and the policy is not set,
+falling back to using ``OLD`` behavior.  Use the :command:`cmake_policy`
+command to set it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/ExternalProject-FetchContent-relative-git-remotes.rst b/Help/release/dev/ExternalProject-FetchContent-relative-git-remotes.rst
new file mode 100644
index 0000000000..d467620a39
--- /dev/null
+++ b/Help/release/dev/ExternalProject-FetchContent-relative-git-remotes.rst
@@ -0,0 +1,7 @@
+ExternalProject-FetchContent-Relative-git-remotes
+-------------------------------------------------
+
+* The :module:`ExternalProject` and :module:`FetchContent` modules
+  now resolve relative `GIT_REPOSITORY` paths as relative to the
+  parent project's remote, not as a relative local file system path.
+  See :policy:`CMP0150`.