ref-manual: Updated the PR variable description.

Fixes [YOCTO #9843]

The variable description was very brief.  These changes added some
substance to the description and how the OpenEmbedded build system
uses the variable.

(From yocto-docs rev: cc9117d4e16c56dd54f81804fda94561e61d91a7)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 40 insertions, 2 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 433893b93d..ed735a7eb3 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -9571,8 +9571,46 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             <glossdef>
                 <para role="glossdeffirst">
 <!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
-                    The revision of the recipe.
-                    The default value for this variable is "r0".
+                    The revision of the recipe. The default value for this
+                    variable is "r0".
+                    Subsequent revisions of the recipe conventionally have the
+                    values "r1", "r2", and so forth.
+                    When
+                    <link linkend='var-PV'><filename>PV</filename></link>
+                    increases, <filename>PR</filename> is conventionally reset
+                    to "r0".
+                    <note>
+                        The OpenEmbedded build system does not need the aid of
+                        <filename>PR</filename> to know when to rebuild a
+                        recipe.
+                        The build system uses
+                        <link linkend='var-STAMP'><filename>STAMP</filename></link>
+                        and the
+                        <link linkend='shared-state-cache'>shared state cache</link>
+                        mechanisms.
+                    </note>
+                    The <filename>PR</filename> variable primarily becomes
+                    significant when a package manager dynamically installs
+                    packages on an already built image.
+                    In this case, <filename>PR</filename>, which is the default
+                    value of
+                    <link linkend='var-PKGR'><filename>PKGR</filename></link>,
+                    helps the package manager distinguish which package is the
+                    most recent one in cases where many packages have the same
+                    <filename>PV</filename> (i.e. <filename>PKGV</filename>).
+                    Packages have the same <filename>PV</filename> usually
+                    when the package manager installs the same upstream version
+                    and some of the packages include packaging fixes.
+                    <note>
+                        <filename>PR</filename> does not need to be increased
+                        for changes that do not change the package contents or
+                        metadata.
+                    </note>
+                    Because, manually managing <filename>PR</filename> can be
+                    cumbersome and error-prone, an automated solution exists.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
+                    section for more information.
                 </para>
             </glossdef>
         </glossentry>