2 files changed, 29 insertions, 1 deletions
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 5156b5b..963af9d 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1846,7 +1846,9 @@ the following methods.
   specifies that whenever `find_program` is used to find a program
   named `progname`, Meson should not look it up on the system but
   instead return `program`, which may either be the result of
-  `find_program`, `configure_file` or `executable`.
+  `find_program`, `configure_file` or `executable`. *Since 0.55.0* if a version
+  check is passed to `find_program` for a program that has been overridden with
+  an executable, the current project version is used.
 
   If `program` is an `executable`, it cannot be used during configure.
 
@@ -2460,6 +2462,12 @@ and has the following methods:
 - `path()` which returns a string pointing to the script or executable
   **NOTE:** You should not need to use this method. Passing the object
   itself should work in all cases. For example: `run_command(obj, arg1, arg2)`
+  *Since 0.55.0* this method has been deprecated in favor of `full_path()` for
+  consistency with other returned objects.
+
+- `full_path()` *Since 0.55.0* which returns a string pointing to the script or
+  executable **NOTE:** You should not need to use this method. Passing the object
+  itself should work in all cases. For example: `run_command(obj, arg1, arg2)`.
 
 ### `environment` object
 
diff --git a/docs/markdown/snippets/find_program.md b/docs/markdown/snippets/find_program.md
new file mode 100644
index 0000000..d0bb64d
--- /dev/null
+++ b/docs/markdown/snippets/find_program.md
@@ -0,0 +1,20 @@
+## find_program: Fixes when the program has been overridden by executable
+
+When a program has been overridden by an executable, the returned object of
+find_program() had some issues:
+
+```meson
+# In a subproject:
+exe = executable('foo', ...)
+meson.override_find_program('foo', exe)
+
+# In main project:
+# The version check was crashing meson.
+prog = find_program('foo', version : '>=1.0')
+
+# This was crashing meson.
+message(prog.path())
+
+# New method to be consistent with built objects.
+message(prog.full_path())
+```