dev-manual: Added notes saying you need to work from same branches

Fixes [YOCTO #4601]

Added a couple notes saying that you need to be in matching
branches for meta-intel and poky.

(From yocto-docs rev: 02bd63829b1d98f21183a10707753e9767bfe68e)

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

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>
+        <note><title>Notes</title>
-            The recommended method for setting up the Yocto Project
+            <itemizedlist>
-            <link linkend='source-directory'>Source Directory</link> and the
+                <listitem><para>
-            files for supported BSPs (e.g., <filename>meta-intel</filename>) is to
+                    The recommended method for setting up the Yocto Project
-            use <link linkend='git'>Git</link> to create a local copy of the
+                    <link linkend='source-directory'>Source Directory</link>
-            upstream repositories.
+                    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>
 

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
+           <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board Support Packages (BSPs):</emphasis>
-                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>
+                Developer's Guide for more information on BSP Layers.
-                <para>You can locate the <filename>meta-intel</filename> Git
+                </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>
+                <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
-                <para>Using
+                </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>
+                </literallayout>
-                <para>The same
+                </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.