ref-manual: Added new section on general migration points.

Fixes [YOCTO #4958]

Added a new section to start the Migration chapter.  This
section will hold general migration issues that are not tied
to a specific release.

(From yocto-docs rev: e78ae7c64ae5fa7e7a5b1f804fb40b5690a4e899)

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

1 files changed, 64 insertions, 0 deletions

diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 9356847b95..d51bc4d8fe 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -11,6 +11,70 @@
         release notes for a given release.
     </para>
 
+<section id='general-migration-considerations'>
+    <title>General Migration Considerations</title>
+
+    <para>
+        Some considerations are not tied to a specific Yocto Project
+        release.
+        This section presents information you should consider when
+        migrating to any new Yocto Project release.
+        <itemizedlist>
+            <listitem><para><emphasis>Dealing with Customized Recipes</emphasis>:
+                Issues could arise if you take older recipes that contain
+                customizations and simply copy them forward expecting them
+                to work after you migrate to new Yocto Project metadata.
+                For example, suppose you have a recipe in your layer that is
+                a customized version of a core recipe copied from the earlier
+                release, rather than through the use of an append file.
+                When you migrate to a newer version of Yocto Project, the
+                metadata (e.g. perhaps an include file used by the recipe)
+                could have changed in a way that would break the build.
+                Say, for example, a function is removed from an include file
+                and the customized recipe tries to call that function.
+                </para>
+
+                <para>You could "forward-port" all your customizations in your
+                recipe so that everything works for the new release.
+                However, this is not the optimal solution as you would have
+                to repeat this process with each new release if changes
+                occur that give rise to problems.</para>
+
+                <para>The better solution (where practical) is to use append
+                files (<filename>*.bbappend</filename>) to capture any
+                customizations you want to make to a recipe.
+                Doing so, isolates your changes from the main recipe making
+                them much more manageable.
+                However, sometimes it is not practical to use an append
+                file.
+                A good example of this is when introducing a newer or older
+                version of a recipe in another layer.</para>
+                </listitem>
+            <listitem><para><emphasis>Updating Append Files</emphasis>:
+                Since append files generally only contain your customizations,
+                they often do not need to be adjusted for new releases.
+                However, if the <filename>.bbappend</filename> file is
+                specific to a particular version of the recipe (i.e. its
+                name does not use the % wildcard) and the version of the
+                recipe to which it is appending has changed, then you will
+                at a minimum need to rename the append file to match the
+                name of the recipe file.
+                A mismatch between an append file and its corresponding
+                recipe file (<filename>.bb</filename>) will
+                trigger an error during parsing.</para>
+                <para>Depending on the type of customization the append file
+                applies, other incompatibilities might occur when you
+                upgrade.
+                For example, if your append file applies a patch and the
+                recipe to which it is appending is updated to a newer
+                version, the patch might no longer apply.
+                If this is the case and assuming the patch is still needed,
+                you must modify the patch file so that it does apply.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
 <section id='moving-to-the-yocto-project-1.3-release'>
     <title>Moving to the Yocto Project 1.3 Release</title>