diff --git a/documentation/poky-ref-manual/migration.xml b/documentation/poky-ref-manual/migration.xml
new file mode 100644
index 0000000000..f410fa020f
--- /dev/null
+++ b/documentation/poky-ref-manual/migration.xml
@@ -0,0 +1,235 @@
+ %poky; ] >
+
+
+Migrating to a Newer Yocto Project Release
+
+
+ This chapter provides information you can use to migrate work to a
+ newer Yocto Project release. You can find the same information in the
+ release notes for a given release.
+
+
+
+ Moving to the Yocto Project 1.3 Release
+
+
+ This section provides migration information for moving to the
+ Yocto Project 1.3 Release.
+
+
+
+ Local Configuration
+
+
+ Differences include changes for
+ SSTATE_MIRRORS
+ and bblayers.conf.
+
+
+
+ SSTATE_MIRRORS
+
+
+ The shared state cache (sstate-cache) as pointed to by
+ SSTATE_DIR by default
+ now has two-character subdirectories to prevent there being an issue with too
+ many files in the same directory.
+ Also, native sstate-cache packages will go into a subdirectory named using
+ the distro ID string.
+ If you copy the newly structured sstate-cache to a mirror location
+ (either local or remote) and then point to it in
+ SSTATE_MIRRORS,
+ you need to append "PATH" to the end of the mirror URL so that
+ the path used by BitBake before the mirror substitution is
+ appended to the path used to access the mirror.
+ Here is an example:
+
+ SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
+
+
+
+
+
+ bblayers.conf
+
+
+ The meta-yocto layer has been split into
+ two parts: meta-yocto and
+ meta-yocto-bsp, corresponding to the
+ Poky reference distro configuration and the reference
+ hardware Board Support Packages (BSPs), respectively.
+ When running BitBake or Hob for the first time after upgrading,
+ your conf/bblayers.conf file will be
+ updated to handle this change and you will be asked to
+ re-run/restart for the changes to take effect.
+
+
+
+
+
+ Recipes
+
+
+ Differences include changes for the following:
+
+ Python function whitespace
+ proto= in SRC_URI
+ nativesdk
+ Task recipes
+ IMAGE_FEATURES
+ Removed recipes
+
+
+
+
+ Python Function Whitespace
+
+
+ All Python functions must now use four spaces for indentation.
+ Previously, an inconsistent mix of spaces and tabs existed,
+ which made extending these functions using
+ _append or _prepend
+ complicated given that Python treats whitespace as
+ syntactically significant.
+ If you are defining or extending any Python functions (e.g.
+ populate_packages, do_unpack,
+ do_patch and so forth) in custom recipes
+ or classes, you need to ensure you are using consistent
+ four-space indentation.
+
+
+
+
+ proto= in SRC_URI
+
+
+ Any use of proto= in
+ SRC_URI
+ needs to be changed to protocol=.
+ In particular, this applies to the following URIs:
+
+ svn://
+ bzr://
+ hg://
+ osc://
+
+ Other URIs were already using protocol=.
+ This change improves consistency.
+
+
+
+
+ nativesdk
+
+
+ The suffix nativesdk is now implemented
+ as a prefix, which simplifies a lot of the packaging code for
+ nativesdk recipes.
+ All custom nativesdk recipes and any
+ references need to be updated to use
+ nativesdk-* instead of
+ *-nativesdk.
+
+
+
+
+ Task Recipes
+
+
+ "Task" recipes are now known as "Package groups" and have
+ been renamed from task-*.bb to
+ packagegroup-*.bb.
+ Existing references to the previous task-*
+ names should work in most cases as there is an automatic
+ upgrade path for most packages.
+ However, you should update references in your own recipes and
+ configurations as they could be removed in future releases.
+ You should also rename any custom task-*
+ recipes to packagegroup-*, and change
+ them to inherit packagegroup instead of
+ task, as well as taking the opportunity
+ to remove anything now handled by
+ packagegroup.bbclass, such as providing
+ -dev and -dbg
+ packages, setting
+ LIC_FILES_CHKSUM,
+ and so forth.
+ See the
+ "Package Groups - packagegroup.bbclass"
+ section for further details.
+
+
+
+
+ IMAGE_FEATURES
+
+
+ Image recipes that previously included "apps-console-core"
+ in IMAGE_FEATURES
+ should now include "splash" instead to enable the boot-up
+ splash screen.
+ Retaining "apps-console-core" will still include the splash
+ screen generates a warning.
+ The "apps-x11-core" and "apps-x11-games"
+ IMAGE_FEATURES features have been removed.
+
+
+
+
+ Removed Recipes
+
+
+ The following recipes have been removed.
+ For most of them, it is unlikely that you would have any
+ references to them in your own metadata.
+ However, you should check your metadata against this list to be sure:
+
+ libx11-trim:
+ Replaced by libx11, which has a negligible
+ size difference as compared with modern Xorg.
+ xserver-xorg-lite:
+ Use xserver-xorg, which has a negligible
+ size difference when DRI and GLX modules are not installed.
+ xserver-kdrive:
+ Effectively unmaintained for many years.
+ mesa-xlib:
+ No longer serves any purpose.
+ galago:
+ Replaced by telepathy.
+ gail:
+ Functionality was integrated into GTK+ 2.13.
+ eggdbus:
+ No longer needed.
+ gcc-*-intermediate:
+ The build has been restructured to avoid the need for
+ this step.
+ libgsmd:
+ Unmaintained for many years and now provided by
+ ofono instead.
+ contacts, dates, tasks, eds-tools:
+ Largely unmaintained PIM application suite.
+ It has been moved to meta-gnome
+ in meta-openembedded.
+
+ In addition to the previously listed changes, the
+ meta-demoapps directory has also been removed
+ because the recipes in it were not being maintained and many
+ had become obsolete or broken.
+ Additionally, these recipes were not parsed in the default configuration.
+ Many of these recipes are already provided in an updated and
+ maintained form within OpenEmbedded community layers such as
+ meta-oe and meta-gnome.
+ For the remainder, you can now find them in the
+ meta-extras repository in the
+ Yocto Project source repositories at
+ .
+
+
+
+
+
+
diff --git a/documentation/poky-ref-manual/poky-ref-manual.xml b/documentation/poky-ref-manual/poky-ref-manual.xml
index e405375bbb..f36fab4eb9 100644
--- a/documentation/poky-ref-manual/poky-ref-manual.xml
+++ b/documentation/poky-ref-manual/poky-ref-manual.xml
@@ -89,6 +89,8 @@
+
+