In the illustration, the "kernel.org Branch Point" marks the specific spot (or release) from
which the Yocto Project kernel is created. From this point "up" 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 up the tree. Placing these common features in the
tree this way means features don't have to be duplicated along individual branches of the
structure.
</para>
<para>
From the Yocto Project Baseline Kernel branch points represent specific functionality
for individual 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 a real-time kernel.
</para>
<para>
The real-time kernel branch has common features for all real-time 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 user
that for all practical purposes is the kernel needed for any given set of requirements.
</para>
</section>
<sectionid='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.
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 results in not having to store the same feature twice internally in the
tree.
Rather we store the unique differences required to apply the feature onto the kernel type
in question.
</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, we create 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, only the unique differences for the BSP across
the supported multiple kernels are uniquely stored.
</para>
<para>
While this strategy results in a tree with a significant number of branches, it is
important to realize that from the customer's point of view, there is a linear
path that travels from the baseline kernel.org, 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 customer's perspective, this is the "master" branch.
They do not need not 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 diff 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 user
because the kernel tree is left in this state after cloning and building the kernel.
</para>
</section>
<sectionid='source-code-manager-git'>
<title>Source Code Manager - git</title>
<para>
The Source Code Manager (SCM) is git and it is the obvious mechanism for meeting the
previously mentioned goals.
Not only is it the SCM for kernel.org but git continues to grow in popularity and
supports many different work flows, front-ends and management techniques.
</para>
<note><para>
It should be noted that you can use as much, or as little, of what git has to offer
as is appropriate to your project.
</para></note>
</section>
</section>
<sectionid='kernel-tools'>
<title>Kernel Tools</title>
<para>
Since most standard workflows involve moving forward with an existing tree by
continuing to add and alter the underlying baseline, the tools that manage
Yocto Project's kernel construction are largely hidden from the developer to
present a simplified view of the kernel for ease of use.
</para>
<para>
The fundamental properties of the tools that manage and construct the
kernel are:
<itemizedlist>
<listitem><para>the ability to group patches into named, reusable features</para></listitem>
<listitem><para>to allow top down control of included features</para></listitem>
<listitem><para>the binding of kernel configuration to kernel patches/features</para></listitem>
<listitem><para>the presentation of a seamless git repository that blends Yocto Project value with the kernel.org history and development</para></listitem>
</itemizedlist>
</para>
<!--<para>
The tools that construct a kernel tree will be discussed later in this
document. The following tools form the foundation of the Yocto Project
kernel toolkit:
<itemizedlist>
<listitem><para>git : distributed revision control system created by Linus Torvalds</para></listitem>
<listitem><para>guilt: quilt on top of git</para></listitem>
<listitem><para>*cfg : kernel configuration management and classification</para></listitem>
<listitem><para>kgit*: Yocto Project kernel tree creation and management tools</para></listitem>
<listitem><para>scc : series & configuration compiler</para></listitem>