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>

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 @@
11	release notes for a given release.	11	release notes for a given release.
12	</para>	12	</para>
13		13
		14	<section id='general-migration-considerations'>
		15	<title>General Migration Considerations</title>
		16
		17	<para>
		18	Some considerations are not tied to a specific Yocto Project
		19	release.
		20	This section presents information you should consider when
		21	migrating to any new Yocto Project release.
		22	<itemizedlist>
		23	<listitem><para><emphasis>Dealing with Customized Recipes</emphasis>:
		24	Issues could arise if you take older recipes that contain
		25	customizations and simply copy them forward expecting them
		26	to work after you migrate to new Yocto Project metadata.
		27	For example, suppose you have a recipe in your layer that is
		28	a customized version of a core recipe copied from the earlier
		29	release, rather than through the use of an append file.
		30	When you migrate to a newer version of Yocto Project, the
		31	metadata (e.g. perhaps an include file used by the recipe)
		32	could have changed in a way that would break the build.
		33	Say, for example, a function is removed from an include file
		34	and the customized recipe tries to call that function.
		35	</para>
		36
		37	<para>You could "forward-port" all your customizations in your
		38	recipe so that everything works for the new release.
		39	However, this is not the optimal solution as you would have
		40	to repeat this process with each new release if changes
		41	occur that give rise to problems.</para>
		42
		43	<para>The better solution (where practical) is to use append
		44	files (<filename>*.bbappend</filename>) to capture any
		45	customizations you want to make to a recipe.
		46	Doing so, isolates your changes from the main recipe making
		47	them much more manageable.
		48	However, sometimes it is not practical to use an append
		49	file.
		50	A good example of this is when introducing a newer or older
		51	version of a recipe in another layer.</para>
		52	</listitem>
		53	<listitem><para><emphasis>Updating Append Files</emphasis>:
		54	Since append files generally only contain your customizations,
		55	they often do not need to be adjusted for new releases.
		56	However, if the <filename>.bbappend</filename> file is
		57	specific to a particular version of the recipe (i.e. its
		58	name does not use the % wildcard) and the version of the
		59	recipe to which it is appending has changed, then you will
		60	at a minimum need to rename the append file to match the
		61	name of the recipe file.
		62	A mismatch between an append file and its corresponding
		63	recipe file (<filename>.bb</filename>) will
		64	trigger an error during parsing.</para>
		65	<para>Depending on the type of customization the append file
		66	applies, other incompatibilities might occur when you
		67	upgrade.
		68	For example, if your append file applies a patch and the
		69	recipe to which it is appending is updated to a newer
		70	version, the patch might no longer apply.
		71	If this is the case and assuming the patch is still needed,
		72	you must modify the patch file so that it does apply.
		73	</para></listitem>
		74	</itemizedlist>
		75	</para>
		76	</section>
		77
14	<section id='moving-to-the-yocto-project-1.3-release'>	78	<section id='moving-to-the-yocto-project-1.3-release'>
15	<title>Moving to the Yocto Project 1.3 Release</title>	79	<title>Moving to the Yocto Project 1.3 Release</title>
16		80