dev-manual: Added "Properly Versioning Pre-Release Recipes" section.

Fixes [YOCTO #6243]

This section addresses situations when working with recipe
file names of recipes that have not been released (e.g.
recipe-name_1.0.3.rc1).  When the recipe is released the system
has difficulty recognizing the new recipe name as a later version.
So the work-around is to use PV to set the recipe version in
the recipe.  The section describes this.

(From yocto-docs rev: a98754620e0285d28f20fd507a68496e8a4364dc)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 38 insertions, 1 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 445ca1750b..bead56c978 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1278,7 +1278,7 @@
                     <literallayout class='monospaced'>
      cups_1.7.0.bb
      gawk_4.0.2.bb
-     xdg-utils_1.1.0-rc1.bb
+     irssi_0.8.16-rc1.bb
                     </literallayout></para></listitem>
             </itemizedlist>
         </section>
@@ -2147,6 +2147,43 @@
             </para>
         </section>
 
+        <section id='properly-versioning-pre-release-recipes'>
+            <title>Properly Versioning Pre-Release Recipes</title>
+
+            <para>
+                Sometimes the name of a recipe can lead to versioning
+                problems when the recipe is upgraded to a final release.
+                For example, consider the
+                <filename>irssi_0.8.16-rc1.bb</filename> recipe file in
+                the list of example recipes in the
+                "<link linkend='new-recipe-storing-and-naming-the-recipe'>Storing and Naming the Recipe</link>"
+                section.
+                This recipe is at a release candidate stage (i.e.
+                "rc1").
+                When the recipe is released, the recipe filename becomes
+                <filename>irssi_0.8.16.bb</filename>.
+                The version change from <filename>0.8.16-rc1</filename>
+                to <filename>0.8.16</filename> is seen as a decrease by the
+                build system and package managers, so the resulting packages
+                will not correctly trigger an upgrade.
+            </para>
+
+            <para>
+                In order to ensure the versions compare properly, the
+                recommended convention is to set
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
+                within the recipe to
+                "&lt;previous version&gt;+&lt;current version&gt;".
+                You can use an additional variable so that you can use the
+                current version elsewhere.
+                Here is an example:
+                <literallayout class='monospaced'>
+     REALPV = "0.8.16-rc1"
+     PV = "0.8.15+${REALPV}"
+                </literallayout>
+            </para>
+        </section>
+
         <section id='new-recipe-post-installation-scripts'>
             <title>Post-Installation Scripts</title>