[gnome-continuous-yocto/gnomeostree-3.28-rocko: 2643/8267] ref-manual: Added note to PREFERRED_VERSION

[Emmanuele Bassi <ebassi src gnome org>]

commit 4824bb4fdaf0778620658d1a901509ad76ad2092
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Tue Sep 13 11:40:43 2016 -0700

    ref-manual: Added note to PREFERRED_VERSION
    
    fixes [YOCTO #10252]
    
    Added a note to help avoid confusion regarding the version
    specification used in PREFERRED_VERSION.
    
    (From yocto-docs rev: 38edc25b04c1a6d673ceb25f5548898d5b63b120)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 documentation/ref-manual/ref-variables.xml |   25 +++++++++++++++++++++++++
 1 files changed, 25 insertions(+), 0 deletions(-)
---
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 188cd74..21c1e42 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%"
                     </literallayout>
+                    <note>
+                        The specified version is matched against
+                        <link linkend='var-PV'><filename>PV</filename></link>,
+                        which does not necessarily match the version part of
+                        the recipe's filename.
+                        For example, consider two recipes
+                        <filename>foo_1.2.bb</filename> and
+                        <filename>foo_git.bb</filename> where
+                        <filename>foo_git.bb</filename> contains the following
+                        assignment:
+                        <literallayout class='monospaced'>
+     PV = "1.1+git${SRCPV}"
+                        </literallayout>
+                        In this case, the correct way to select
+                        <filename>foo_git.bb</filename> is by using an
+                        assignment such as the following:
+                        <literallayout class='monospaced'>
+     PREFERRED_VERSION_foo = "1.1+git%"
+                        </literallayout>
+                        Compare that previous example against the following
+                        incorrect example, which does not work:
+                        <literallayout class='monospaced'>
+     PREFERRED_VERSION_foo = "git"
+                        </literallayout>
+                    </note>
                     Sometimes the <filename>PREFERRED_VERSION</filename>
                     variable can be set by configuration files in a way that
                     is hard to change.