kernel-dev: Re-write of Yocto Linux Architecture and Branch Strategies

This section in Appepndix A was full of redundancies used to
explain how the Yocto Project kernel development team has set
up branching and kernel architecture.  I consolidated a couple
sub-sections into just the necessary single section.

(From yocto-docs rev: e42efe28aec6bad3779c4b9ea58941272fb01651)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 192 insertions, 182 deletions

diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index 21f7c2c686..7c9f34c729 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -173,202 +173,212 @@
         </para>
     </section>
 
-    <section id='kernel-architecture'>
-        <title>Kernel Architecture</title>
+    <section id='yocto-linux-kernel-architecture-and-branching-strategies'>
+        <title>Yocto Linux Kernel Architecture and Branching Strategies</title>
 
         <para>
-            This section describes the architecture of the Yocto Linux kernels
-            available through the Yocto Project and provides information
-            on the mechanisms used to achieve that architecture.
+            As mentioned earlier, a key goal of the Yocto Project is
+            to present the developer with a kernel that has a clear and
+            continuous history that is visible to the user.
+            The architecture and mechanisms, in particular the branching
+            strategies, used achieve that goal in a manner similar to
+            upstream Linux kernel development in
+            <filename>kernel.org</filename>.
         </para>
 
-        <section id='architecture-overview'>
-            <title>Overview</title>
+        <para>
+            You can think of a Yocto Linux kernel as consisting of a
+            baseline Linux kernel with added features logically structured
+            on top of the baseline.
+            The features are tagged and organized by way of a branching
+            strategy implemented by the Yocto Project team using the
+            Source Code Manager (SCM) Git.
+            <note><title>Notes</title>
+                <itemizedlist>
+                    <listitem><para>
+                        Git is the obvious SCM for meeting the Yocto Linux
+                        kernel organizational and structural goals
+                        described in this section.
+                        Not only is Git the SCM for Linux kernel
+                        development in <filename>kernel.org</filename> but,
+                        Git continues to grow in popularity and supports
+                        many different work flows, front-ends and
+                        management techniques.
+                        </para></listitem>
+                    <listitem><para>
+                        You can find documentation on Git at
+                        <ulink url='http://git-scm.com/documentation'></ulink>.
+                        You can also get an introduction to Git as it
+                        applies to the Yocto Project in the
+                        "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>"
+                        section in the Yocto Project Reference Manual.
+                        The latter reference provides an overview of
+                        Git and presents a minimal set of Git commands
+                        that allows you to be functional using Git.
+                        You can use as much, or as little, of what Git
+                        has to offer to accomplish what you need for your
+                        project.
+                        You do not have to be a "Git Expert" in order to
+                        use it with the Yocto Project.
+                        </para></listitem>
+                </itemizedlist>
+            </note>
+        </para>
 
-            <para>
-                As mentioned earlier, a key goal of the Yocto Project is
-                to present the developer with a kernel that has a clear and
-                continuous history that is visible to the user.
-                The architecture and mechanisms used achieve that goal in a
-                manner similar to upstream Linux kernel development in
-                <filename>kernel.org</filename>.
-            </para>
+        <para>
+            Using Git's tagging and branching features, the Yocto Project
+            team creates kernel branches at points where functionality is
+            no longer shared and thus, needs to be isolated.
+            For example, board-specific incompatibilities would require
+            different functionality and would require a branch to
+            separate the features.
+            Likewise, for specific kernel features, the same branching
+            strategy is used.
+        </para>
 
-            <para>
-                You can think of a Yocto Linux kernel as consisting of a
-                baseline Linux kernel with added features logically structured
-                on top of the baseline.
-                The features are tagged and organized by way of a branching
-                strategy implemented by the Yocto Project team using the
-                Source Code Manager (SCM) Git.
-                <note><title>Notes</title>
-                    <itemizedlist>
-                        <listitem><para>
-                            Git is the obvious SCM for meeting the Yocto Linux
-                            kernel organizational and structural goals
-                            described in this section.
-                            Not only is Git the SCM for Linux kernel
-                            development in <filename>kernel.org</filename> but,
-                            Git continues to grow in popularity and supports
-                            many different work flows, front-ends and
-                            management techniques.
-                            </para></listitem>
-                        <listitem><para>
-                            You can find documentation on Git at
-                            <ulink url='http://git-scm.com/documentation'></ulink>.
-                            You can also get an introduction to Git as it
-                            applies to the Yocto Project in the
-                            "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>"
-                            section in the Yocto Project Reference Manual.
-                            The latter reference provides an overview of
-                            Git and presents a minimal set of Git commands
-                            that allows you to be functional using Git.
-                            You can use as much, or as little, of what Git
-                            has to offer to accomplish what you need for your
-                            project.
-                            You do not have to be a "Git Expert" in order to
-                            use it with the Yocto Project.
-                            </para></listitem>
-                    </itemizedlist>
-                </note>
-            </para>
+        <para>
+            This "tree-like" architecture results in a tree that has
+            features organized to be specific for particular
+            functionality, single kernel types, or a subset of kernel
+            types.
+            Thus, the user has the ability to see the added
+            features and the commits that make up those features.
+            In addition to being able to see added features, the user
+            can also view the history of what made up the baseline
+            Linux kernel.
+        </para>
 
-            <para>
-                The result is that the user has the ability to see the added
-                features and the commits that make up those features.
-                In addition to being able to see added features, the user
-                can also view the history of what made up the baseline
-                Linux kernel.
-            </para>
+        <para>
+            Another consequence of this strategy results in not having to
+            store the same feature twice internally in the tree.
+            Rather, the kernel team stores the unique differences required
+            to apply the feature onto the kernel type in question.
+            <note>
+                The Yocto Project team strives to place features in the tree
+                such that features can be shared by all boards and kernel
+                types where possible.
+                However, during development cycles or when large features
+                are merged, the team cannot always follow this practice.
+                In those cases, the team uses isolated branches to merge
+                features.
+            </note>
+        </para>
 
-            <para>
-                The following illustration shows the conceptual Yocto
-                Linux kernel.
-                <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
-            </para>
+        <para>
+            BSP-specific code additions are handled in a similar manner to
+            kernel-specific additions.
+            Some BSPs only make sense given certain kernel types.
+            So, for these types, the team creates branches off the end
+            of that kernel type for all of the BSPs that are supported on
+            that kernel type.
+            From the perspective of the tools that create the BSP branch,
+            the BSP is really no different than a feature.
+            Consequently, the same branching strategy applies to BSPs as
+            it does to kernel features.
+            So again, rather than store the BSP twice, the team only
+            stores the unique differences for the BSP across the supported
+            multiple kernels.
+        </para>
 
-            <para>
-                In the illustration, the "Kernel.org Branch Point" marks the
-                specific spot (or Linux kernel release) from which the
-                Yocto Linux kernel is created.
-                From this point forward in the tree, features and differences
-                are organized and tagged.
-            </para>
+        <para>
+            While this strategy can result in a tree with a significant number
+            of branches, it is important to realize that from the developer's
+            point of view, there is a linear path that travels from the
+            baseline <filename>kernel.org</filename>, through a select
+            group of features and ends with their BSP-specific commits.
+            In other words, the divisions of the kernel are transparent and
+            are not relevant to the developer on a day-to-day basis.
+            From the developer's perspective, this path is the "master" branch
+            in Git terms.
+            The developer does not need to be aware of the existence of any
+            other branches at all.
+            Of course, value exists in the having these branches in the tree,
+            should a person decide to explore them.
+            For example, a comparison between two BSPs at either the commit
+            level or at the line-by-line code <filename>diff</filename> level
+            is now a trivial operation.
+        </para>
 
-            <para>
-                The "Yocto Project Baseline Kernel" contains functionality that
-                is common to every kernel type and BSP that is organized
-                further along in the tree.
-                Placing these common features in the tree this way means
-                features do not have to be duplicated along individual
-                branches of the tree structure.
-            </para>
+        <para>
+            The following illustration shows the conceptual Yocto
+            Linux kernel.
+            <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
+        </para>
+
+        <para>
+            In the illustration, the "Kernel.org Branch Point" marks the
+            specific spot (or Linux kernel release) from which the
+            Yocto Linux kernel is created.
+            From this point forward in the tree, features and differences
+            are organized and tagged.
+        </para>
+
+        <para>
+            The "Yocto Project Baseline Kernel" contains functionality that
+            is common to every kernel type and BSP that is organized
+            further along in the tree.
+            Placing these common features in the tree this way means
+            features do not have to be duplicated along individual
+            branches of the tree structure.
+        </para>
+
+        <para>
+            From the "Yocto Project Baseline Kernel", branch points represent
+            specific functionality for individual Board Support Packages
+            (BSPs) as well as real-time kernels.
+            The illustration represents this through three BSP-specific
+            branches and a real-time kernel branch.
+            Each branch represents some unique functionality for the BSP
+            or for a real-time Yocto Linux kernel.
+        </para>
 
-            <para>
-                From the Yocto Project Baseline Kernel, branch points represent
-                specific functionality for individual Board Support Packages
-                (BSPs) as well as real-time kernels.
-                The illustration represents this through three BSP-specific
-                branches and a real-time kernel branch.
-                Each branch represents some unique functionality for the BSP
-                or for a real-time Yocto Linux kernel.
-            </para>
+        <para>
+            In this example structure, the "Real-time (rt) Kernel" branch has
+            common features for all real-time Yocto Linux kernels and
+            contains more branches for individual BSP-specific real-time
+            kernels.
+            The illustration shows three branches as an example.
+            Each branch points the way to specific, unique features for a
+            respective real-time kernel as they apply to a given BSP.
+        </para>
 
-            <para>
-                In this example structure, the real-time kernel branch has
-                common features for all real-time Yocto Linux kernels and
-                contains more branches for individual BSP-specific real-time
-                kernels.
-                The illustration shows three branches as an example.
-                Each branch points the way to specific, unique features for a
-                respective real-time kernel as they apply to a given BSP.
-            </para>
+        <para>
+            The resulting tree structure presents a clear path of markers
+            (or branches) to the developer that, for all practical
+            purposes, is the Yocto Linux kernel needed for any given set of
+            requirements.
+            <note>
+                Keep in mind the figure does not take into account all the
+                supported Yocto Linux kernels, but rather shows a single
+                generic kernel just for conceptual purposes.
+                Also keep in mind that this structure represents the Yocto
+                Project
+                <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
+                that are either pulled from during the build or established
+                on the host development system prior to the build by either
+                cloning a particular kernel's Git repository or by
+                downloading and unpacking a tarball.
+            </note>
+        </para>
 
-            <para>
-                The resulting tree structure presents a clear path of markers
-                (or branches) to the developer that, for all practical
-                purposes, is the Yocto Linux kernel needed for any given set of
-                requirements.
-                <note>
-                    Keep in mind the figure does not take into account all the
-                    supported Yocto Linux kernels, but rather shows a single
-                    generic kernel just for conceptual purposes.
-                    Also keep in mind that this structure represents the Yocto
-                    Project
-                    <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
-                    that are either pulled from during the build or established
-                    on the host development system prior to the build by either
-                    cloning a particular kernel's Git repository or by
-                    downloading and unpacking a tarball.
-                </note>
-            </para>
-        </section>
+        <para>
+            Working with the kernel as a structured tree follows recognized
+            community best practices.
+            In particular, the kernel as shipped with the product, should be
+            considered an "upstream source" and viewed as a series of
+            historical and documented modifications (commits).
+            These modifications represent the development and stabilization
+            done by the Yocto Project kernel development team.
+        </para>
 
-        <section id='branching-and-workflow'>
-            <title>Branching Strategy and Workflow</title>
-            <para>
-                The Yocto Project team creates kernel branches at points where functionality is
-                no longer shared and thus, needs to be isolated.
-                For example, board-specific incompatibilities would require different functionality
-                and would require a branch to separate the features.
-                Likewise, for specific kernel features, the same branching strategy is used.
-            </para>
-            <para>
-                This branching strategy results in a tree that has features organized to be specific
-                for particular functionality, single kernel types, or a subset of kernel types.
-                This strategy also results in not having to store the same feature twice
-                internally in the tree.
-                Rather, the kernel team stores the unique differences required to apply the
-                feature onto the kernel type in question.
-                <note>
-                    The Yocto Project team strives to place features in the tree such that they can be
-                    shared by all boards and kernel types where possible.
-                    However, during development cycles or when large features are merged,
-                    the team cannot always follow this practice.
-                    In those cases, the team uses isolated branches to merge features.
-                </note>
-            </para>
-            <para>
-                BSP-specific code additions are handled in a similar manner to kernel-specific additions.
-                Some BSPs only make sense given certain kernel types.
-                So, for these types, the team creates branches off the end of that kernel type for all
-                of the BSPs that are supported on that kernel type.
-                From the perspective of the tools that create the BSP branch, the BSP is really no
-                different than a feature.
-                Consequently, the same branching strategy applies to BSPs as it does to features.
-                So again, rather than store the BSP twice, the team only stores the unique
-                differences for the BSP across the supported multiple kernels.
-            </para>
-            <para>
-                While this strategy can result in a tree with a significant number of branches, it is
-                important to realize that from the developer's point of view, there is a linear
-                path that travels from the baseline <filename>kernel.org</filename>, through a select
-                group of features and ends with their BSP-specific commits.
-                In other words, the divisions of the kernel are transparent and are not relevant
-                to the developer on a day-to-day basis.
-                From the developer's perspective, this path is the "master" branch.
-                The developer does not need to be aware of the existence of any other branches at all.
-                Of course, there is value in the existence of these branches
-                in the tree, should a person decide to explore them.
-                For example, a comparison between two BSPs at either the commit level or at the line-by-line
-                code <filename>diff</filename> level is now a trivial operation.
-            </para>
-            <para>
-                Working with the kernel as a structured tree follows recognized community best practices.
-                In particular, the kernel as shipped with the product, should be
-                considered an "upstream source" and viewed as a series of
-                historical and documented modifications (commits).
-                These modifications represent the development and stabilization done
-                by the Yocto Project kernel development team.
-            </para>
-            <para>
-                Because commits only change at significant release points in the product life cycle,
-                developers can work on a branch created
-                from the last relevant commit in the shipped Yocto Project kernel.
-                As mentioned previously, the structure is transparent to the developer
-                because the kernel tree is left in this state after cloning and building the kernel.
-            </para>
-        </section>
+        <para>
+            Because commits only change at significant release points in the
+            product life cycle, developers can work on a branch created
+            from the last relevant commit in the shipped Yocto Project kernel.
+            As mentioned previously, the structure is transparent to the
+            developer because the kernel tree is left in this state after
+            cloning and building the kernel.
+        </para>
     </section>
 </appendix>
 <!--