diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 188cd74935..21c1e42388 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -9999,6 +9999,31 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
PREFERRED_VERSION_python = "3.4.0"
PREFERRED_VERSION_linux-yocto = "3.19%"
+
+ The specified version is matched against
+ PV,
+ which does not necessarily match the version part of
+ the recipe's filename.
+ For example, consider two recipes
+ foo_1.2.bb and
+ foo_git.bb where
+ foo_git.bb contains the following
+ assignment:
+
+ PV = "1.1+git${SRCPV}"
+
+ In this case, the correct way to select
+ foo_git.bb is by using an
+ assignment such as the following:
+
+ PREFERRED_VERSION_foo = "1.1+git%"
+
+ Compare that previous example against the following
+ incorrect example, which does not work:
+
+ PREFERRED_VERSION_foo = "git"
+
+
Sometimes the PREFERRED_VERSION
variable can be set by configuration files in a way that
is hard to change.