kernel-dev: Created super section for Branches.

The sections for "Machine Branches" and "Feature Branches" really
should be encapsulated within a section on branching.  Much of
the text in the "Machine Branches" section presents the rationale
behind both types of branches.  I have created a larger section
to contain these and will edit the text to fit.

(From yocto-docs rev: c7c67f5867f22ebbbd49cab79bb2d4e52422ecac)

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

1 files changed, 115 insertions, 103 deletions

diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index ff8374c635..d02654f13a 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -1373,47 +1373,58 @@ the KTYPE has changed, now set to "tiny".
     </section>
 </section>
 
-<section id='machine-branches'>
-    <title>Machine Branches</title>
+<section id='working-with-branches'>
+    <title>Working with Branches</title>
 
     <para>
-        The "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
-        section introduced the <filename>KBRANCH</filename> variable, which
-        defines the source branch to use from the Linux kernel Git repository
-        you are using.
-        Many linux-yocto-custom derived recipes will be using Linux kernel
-        sources with only a single branch: "master".
-        However, when you are working with multiple boards and architectures,
-        you are likely to run into the situation where a series of patches
-        are needed for one board to boot.
-        Sometimes, these patches are works-in-progress or fundamentally wrong,
-        yet still necessary for specific boards.
-        In these situations, you most likely do not want to include these
-        patches in every kernel you build.
-        You have a couple of options.
+        We need a top-level section here that introduces branches in general.
+        There is information that can be pulled from the embedded machine
+        and feature sections to introduce this stuff.
+        The two subsections should deal with each type of specific branch
+        that can be used.
     </para>
 
-    <para>
-        First, you could encapsulate these patches in a feature description
-        and only include them in the BSP description for the board(s) that
-        require them.
-        For more information, see the
-        "<link linkend='patches'>Patches</link>" and
-        "<link linkend='bsp-descriptions'>BSP Descriptions</link>" sections.
-    </para>
+    <section id='machine-branches'>
+        <title>Machine Branches</title>
 
-    <para>
-        Alternatively, you can create a branch in your Linux kernel sources
-        and apply the patches there.
-        You can then specify this new branch as the
-        <filename>KBRANCH</filename> to use for this board.
-        You can do this in the recipe with the
-        <filename>KBRANCH</filename> variable:
-        <literallayout class='monospaced'>
+        <para>
+            The "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
+            section introduced the <filename>KBRANCH</filename> variable, which
+            defines the source branch to use from the Linux kernel Git repository
+            you are using.
+            Many linux-yocto-custom derived recipes will be using Linux kernel
+            sources with only a single branch: "master".
+            However, when you are working with multiple boards and architectures,
+            you are likely to run into the situation where a series of patches
+            are needed for one board to boot.
+            Sometimes, these patches are works-in-progress or fundamentally wrong,
+            yet still necessary for specific boards.
+            In these situations, you most likely do not want to include these
+            patches in every kernel you build.
+            You have a couple of options.
+        </para>
+
+        <para>
+            First, you could encapsulate these patches in a feature description
+            and only include them in the BSP description for the board(s) that
+            require them.
+            For more information, see the
+            "<link linkend='patches'>Patches</link>" and
+            "<link linkend='bsp-descriptions'>BSP Descriptions</link>" sections.
+        </para>
+
+        <para>
+            Alternatively, you can create a branch in your Linux kernel sources
+            and apply the patches there.
+            You can then specify this new branch as the
+            <filename>KBRANCH</filename> to use for this board.
+            You can do this in the recipe with the
+            <filename>KBRANCH</filename> variable:
+           <literallayout class='monospaced'>
      KBRANCH = "mynewbranch"
-        </literallayout>
-        or in the BSP description using the "branch" command:
-        <literallayout class='monospaced'>
+            </literallayout>
+            or in the BSP description using the "branch" command:
+            <literallayout class='monospaced'>
      mybsp.scc:
         define KMACHINE mybsp
         define KTYPE standard
@@ -1423,35 +1434,35 @@ the KTYPE has changed, now set to "tiny".
         branch mynewbranch
 
         include mybsp-hw.scc
-        </literallayout>
-    </para>
+            </literallayout>
+        </para>
 
-    <para>
-        The approach you take, feature or branch, is entirely up to you
-        and depends on what works best for your development model.
-        If you are actively working on board support, you may find that
-        working within a branch is more practical than trying to continually
-        reintegrate your patches into a feature.
-        On the other hand, if you are simply reusing some patches from an
-        external tree and are not working on them, you may find the
-        encapsulated feature to be appropriate as it does not require the
-        additional complexity of branching in your Linux kernel sources.
-    </para>
+        <para>
+            The approach you take, feature or branch, is entirely up to you
+            and depends on what works best for your development model.
+            If you are actively working on board support, you may find that
+            working within a branch is more practical than trying to continually
+            reintegrate your patches into a feature.
+            On the other hand, if you are simply reusing some patches from an
+            external tree and are not working on them, you may find the
+            encapsulated feature to be appropriate as it does not require the
+            additional complexity of branching in your Linux kernel sources.
+        </para>
 
-    <para>
-        If you are supporting multiple boards and architectures and find
-        yourself with numerous branches, you might consider using a
-        hierarchical branching system similar to what the linux-yocto Linux
-        kernel repositories use:
-        <literallayout class='monospaced'>
+        <para>
+            If you are supporting multiple boards and architectures and find
+            yourself with numerous branches, you might consider using a
+            hierarchical branching system similar to what the linux-yocto Linux
+            kernel repositories use:
+            <literallayout class='monospaced'>
      &lt;common&gt;/&lt;ktype&gt;/&lt;machine&gt;
-        </literallayout>
-    </para>
+            </literallayout>
+        </para>
 
-    <para>
-        If you had two ktypes, standard and small for instance, and three
-        machines, your Git tree might look like this:
-        <literallayout class='monospaced'>
+        <para>
+            If you had two ktypes, standard and small for instance, and three
+            machines, your Git tree might look like this:
+            <literallayout class='monospaced'>
      common/base
      common/standard/base
      common/standard/machine_a
@@ -1459,27 +1470,27 @@ the KTYPE has changed, now set to "tiny".
      common/standard/machine_c
      common/small/base
      common/small/machine_a
-        </literallayout>
-    </para>
+            </literallayout>
+        </para>
 
-    <para>
-        This organization can help clarify the relationship of the branches to
-        each other.
-        In this case, "common/standard/machine_a" would include everything in
-        "common/base" and "common/standard/base".
-        The "standard" and "small" branches add sources specific to those
-        kernel types that for whatever reason are not appropriate for the
-        other branches.
-        <note>The "base" branches are an artifact of the way Git manages
-            its data internally on the filesystem: it will not allow you to use
-            "common/standard" and "common/standard/machine_a" because it
-            would have to create a file and a directory named "standard".
-        </note>
-    </para>
+        <para>
+            This organization can help clarify the relationship of the branches to
+            each other.
+            In this case, "common/standard/machine_a" would include everything in
+            "common/base" and "common/standard/base".
+            The "standard" and "small" branches add sources specific to those
+            kernel types that for whatever reason are not appropriate for the
+            other branches.
+            <note>The "base" branches are an artifact of the way Git manages
+                its data internally on the filesystem: it will not allow you to use
+                "common/standard" and "common/standard/machine_a" because it
+                would have to create a file and a directory named "standard".
+            </note>
+        </para>
 
-    <para>
-        Original text:
-        <literallayout class='monospaced'>
+        <para>
+            Original text:
+            <literallayout class='monospaced'>
 Section 3.1 introduced the KBRANCH variable which defines the source branch to
 use from the Linux kernel git repository you are using. Many linux-yocto-custom
 derived recipes will be using Linux kernel sources with only a single branch:
@@ -1548,26 +1559,26 @@ Note: The "base" branches are an artifact of the way git manages its data
       internally on the filesystem: it will not allow you to use
       "common/standard" and "common/standard/machine_a" because it would have to
       create a file and a directory named "standard".
-        </literallayout>
-    </para>
-</section>
+            </literallayout>
+        </para>
+    </section>
 
-<section id='feature-branches'>
-    <title>Feature Branches</title>
+    <section id='feature-branches'>
+        <title>Feature Branches</title>
 
-    <para>
-        During active development a new feature, it can be more efficient
-        to work with that feature as a branch, rather than as a set of
-        patches which have to be regularly updated.
-        The Yocto Project Linux kernel tools provide for this with
-        the <filename>git merge</filename> command.
-    </para>
+        <para>
+            During active development a new feature, it can be more efficient
+            to work with that feature as a branch, rather than as a set of
+            patches which have to be regularly updated.
+            The Yocto Project Linux kernel tools provide for this with
+            the <filename>git merge</filename> command.
+        </para>
 
-    <para>
-        To merge a feature branch into a BSP, insert the
-        <filename>git merge</filename> command after any
-        <filename>branch</filename> commands:
-        <literallayout class='monospaced'>
+        <para>
+            To merge a feature branch into a BSP, insert the
+            <filename>git merge</filename> command after any
+            <filename>branch</filename> commands:
+            <literallayout class='monospaced'>
      mybsp.scc:
         define KMACHINE mybsp
         define KTYPE standard
@@ -1578,12 +1589,12 @@ Note: The "base" branches are an artifact of the way git manages its data
         git merge myfeature
 
         include mybsp-hw.scc
-        </literallayout>
-    </para>
+            </literallayout>
+        </para>
 
-    <para>
-        Original text:
-        <literallayout class='monospaced'>
+        <para>
+            Original text:
+            <literallayout class='monospaced'>
 During active development a new feature, it can be more efficient to work with
 that feature as a branch, rather than as a set of patches which have to be
 regularly updated. The Yocto Project Linux kernel tools provide for this with
@@ -1602,8 +1613,9 @@ mybsp.scc:
 	git merge myfeature
 
 	include mybsp.scc
-        </literallayout>
-    </para>
+            </literallayout>
+        </para>
+    </section>
 </section>
 
 <section id='scc-reference'>