2 files changed, 48 insertions, 14 deletions

diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 77c14a6611..1245345cc4 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -431,12 +431,27 @@
         <filename>poky</filename> repository or any supported BSP tarballs.
         Unpacking these tarballs gives you a snapshot of the released
         files.
-        <note>
-            The recommended method for setting up the Yocto Project
-            <link linkend='source-directory'>Source Directory</link> and the
-            files for supported BSPs (e.g., <filename>meta-intel</filename>) is to
-            use <link linkend='git'>Git</link> to create a local copy of the
-            upstream repositories.
+        <note><title>Notes</title>
+            <itemizedlist>
+                <listitem><para>
+                    The recommended method for setting up the Yocto Project
+                    <link linkend='source-directory'>Source Directory</link>
+                    and the files for supported BSPs
+                    (e.g., <filename>meta-intel</filename>) is to use
+                    <link linkend='git'>Git</link> to create a local copy of
+                    the upstream repositories.
+                    </para></listitem>
+                <listitem><para>
+                    Be sure to always work in matching branches for both
+                    the <filename>meta-intel</filename> repository and the
+                    <link linkend='source-directory'>Source Directory</link>
+                    (i.e. <filename>poky</filename>) repository.
+                    For example, if you have checked out the "master" branch
+                    of <filename>poky</filename> and you are going to use
+                    <filename>meta-intel</filename>, be sure to checkout the
+                    "master" branch of <filename>meta-intel</filename>.
+                    </para></listitem>
+            </itemizedlist>
         </note>
     </para>
 
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index deea5a7610..6ab93f79cf 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -187,8 +187,7 @@
      Receiving objects: 100% (727/727), 536.36 KiB | 240 KiB/s, done.
      Resolving deltas: 100% (260/260), done.
                </literallayout></para></listitem>
-           <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board
-                Support Packages (BSPs):</emphasis>
+           <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board Support Packages (BSPs):</emphasis>
                 The Yocto Project provides a layer called
                 <filename>meta-intel</filename> and it is maintained in its own
                 separate Git repository.
@@ -196,6 +195,7 @@
                 supported
                 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.
                 </para>
+
                 <para>The Yocto Project uses the following BSP layer naming
                 scheme:
                 <literallayout class='monospaced'>
@@ -212,12 +212,18 @@
                 See the
                 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
                 section in the Yocto Project Board Support Package (BSP)
-                Developer's Guide for more information on BSP Layers.</para>
-                <para>You can locate the <filename>meta-intel</filename> Git
+                Developer's Guide for more information on BSP Layers.
+                </para>
+
+                <para>
+                You can locate the <filename>meta-intel</filename> Git
                 repository in the "Yocto Metadata Layers" area of the Yocto
                 Project Source Repositories at
-                <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
-                <para>Using
+                <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
+                </para>
+
+                <para>
+                Using
                 <link linkend='git'>Git</link> to create a local clone of the
                 upstream repository can be helpful if you are working with
                 BSPs.
@@ -225,6 +231,16 @@
                 Git repository inside the Source Directory.
                 For example, the following transcript shows the steps to clone
                 <filename>meta-intel</filename>.
+                <note>
+                    Be sure to work in the <filename>meta-intel</filename>
+                    branch that matches your
+                    <link linkend='source-directory'>Source Directory</link>
+                    (i.e. <filename>poky</filename>) branch.
+                    For example, if you have checked out the "master" branch
+                    of <filename>poky</filename> and you are going to use
+                    <filename>meta-intel</filename>, be sure to checkout the
+                    "master" branch of <filename>meta-intel</filename>.
+                </note>
                 <literallayout class='monospaced'>
      $ cd ~/poky
      $ git clone git://git.yoctoproject.org/meta-intel.git
@@ -234,8 +250,11 @@
      remote: Total 8844 (delta 4931), reused 8780 (delta 4867)
      Receiving objects: 100% (8844/8844), 2.48 MiB | 264 KiB/s, done.
      Resolving deltas: 100% (4931/4931), done.
-                </literallayout></para>
-                <para>The same
+                </literallayout>
+                </para>
+
+                <para>
+                The same
                 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>wiki page</ulink>
                 referenced earlier covers how to set up the
                 <filename>meta-intel</filename> Git repository.