990 lines
51 KiB
XML
990 lines
51 KiB
XML
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
||
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
||
|
||
<chapter id='dev-manual-newbie'>
|
||
|
||
<title>The Yocto Project Open Source Development Environment</title>
|
||
|
||
<section id="usingpoky-changes-collaborate">
|
||
<title>Setting Up a Team Yocto Project Development Environment</title>
|
||
|
||
<para>
|
||
It might not be immediately clear how you can use the Yocto
|
||
Project in a team development environment, or scale it for a large
|
||
team of developers.
|
||
One of the strengths of the Yocto Project is that it is extremely
|
||
flexible.
|
||
Thus, you can adapt it to many different use cases and scenarios.
|
||
However, these characteristics can cause a struggle if you are trying
|
||
to create a working setup that scales across a large team.
|
||
</para>
|
||
|
||
<para>
|
||
To help you understand how to set up this type of environment,
|
||
this section presents a procedure that gives you the information
|
||
to learn how to get the results you want.
|
||
The procedure is high-level and presents some of the project's most
|
||
successful experiences, practices, solutions, and available
|
||
technologies that work well.
|
||
Keep in mind, the procedure here is a starting point.
|
||
You can build off it and customize it to fit any
|
||
particular working environment and set of practices.
|
||
<orderedlist>
|
||
<listitem><para>
|
||
<emphasis>Determine Who is Going to be Developing:</emphasis>
|
||
You need to understand who is going to be doing anything
|
||
related to the Yocto Project and what their roles would be.
|
||
Making this determination is essential to completing the
|
||
steps two and three, which are to get your equipment together
|
||
and set up your development environment's hardware topology.
|
||
</para>
|
||
|
||
<para>The following roles exist:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<emphasis>Application Development:</emphasis>
|
||
These types of developers do application level work
|
||
on top of an existing software stack.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Core System Development:</emphasis>
|
||
These types of developers work on the contents of the
|
||
operating system image itself.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Build Engineer:</emphasis>
|
||
This type of developer manages Autobuilders and
|
||
releases.
|
||
Not all environments need a Build Engineer.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Test Engineer:</emphasis>
|
||
This type of developer creates and manages automated
|
||
tests needed to ensure all application and core
|
||
system development meets desired quality standards.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Gather the Hardware:</emphasis>
|
||
Based on the size and make-up of the team, get the hardware
|
||
together.
|
||
Any development, build, or test engineer should be using
|
||
a system that is running a supported Linux distribution.
|
||
Systems, in general, should be high performance (e.g. dual,
|
||
six-core Xeons with 24 Gbytes of RAM and plenty of disk space).
|
||
You can help ensure efficiency by having any machines used
|
||
for testing or that run Autobuilders be as high performance
|
||
as possible.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Understand the Hardware Topology of the Environment:</emphasis>
|
||
Now that you know how many developers and support engineers
|
||
are required, you can understand the topology of the
|
||
hardware environment.
|
||
The following figure shows a moderately sized Yocto Project
|
||
development environment.
|
||
|
||
<para role="writernotes">
|
||
Need figure.</para>
|
||
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
|
||
Keeping your
|
||
<ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
|
||
and any software you are developing under the
|
||
control of an SCM system that is compatible
|
||
with the OpenEmbedded build system is advisable.
|
||
Of the SCMs BitBake supports, the
|
||
Yocto Project team strongly recommends using
|
||
<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>.
|
||
Git is a distributed system that is easy to backup,
|
||
allows you to work remotely, and then connects back to the
|
||
infrastructure.
|
||
<note>
|
||
For information about BitBake, see the
|
||
<ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
|
||
</note></para>
|
||
|
||
<para>It is relatively easy to set up Git services and create
|
||
infrastructure like
|
||
<ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
|
||
which is based on server software called
|
||
<filename>gitolite</filename> with <filename>cgit</filename>
|
||
being used to generate the web interface that lets you view the
|
||
repositories.
|
||
The <filename>gitolite</filename> software identifies users
|
||
using SSH keys and allows branch-based
|
||
access controls to repositories that you can control as little
|
||
or as much as necessary.
|
||
|
||
<note>
|
||
The setup of these services is beyond the scope of this
|
||
manual.
|
||
However, sites such as these exist that describe how to
|
||
perform setup:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
|
||
Describes how to install <filename>gitolite</filename>
|
||
on the server.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>:
|
||
All topics for <filename>gitolite</filename>.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
|
||
Documentation on how to create interfaces and frontends
|
||
for Git.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</note>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Set up the Application Development Machines:</emphasis>
|
||
As mentioned earlier, application developers are creating
|
||
applications on top of existing software stacks.
|
||
Following are some best practices for setting up machines
|
||
that do application development:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
Use a pre-built toolchain that
|
||
contains the software stack itself.
|
||
Then, develop the application code on top of the
|
||
stack.
|
||
This method works well for small numbers of relatively
|
||
isolated applications.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
When possible, use the Yocto Project
|
||
plug-in for the
|
||
<trademark class='trade'>Eclipse</trademark> IDE
|
||
and SDK development practices.
|
||
For more information, see the
|
||
"<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>"
|
||
manual.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Keep your cross-development toolchains updated.
|
||
You can do this through provisioning either as new
|
||
toolchain downloads or as updates through a package
|
||
update mechanism using <filename>opkg</filename>
|
||
to provide updates to an existing toolchain.
|
||
The exact mechanics of how and when to do this are a
|
||
question for local policy.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Use multiple toolchains installed locally
|
||
into different locations to allow development across
|
||
versions.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Set up the Core Development Machines:</emphasis>
|
||
As mentioned earlier, these types of developers work on the
|
||
contents of the operating system itself.
|
||
Following are some best practices for setting up machines
|
||
used for developing images:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
Have the Yocto Project build system itself available on
|
||
the developer workstations so developers can run their own
|
||
builds and directly rebuild the software stack.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Keep the core system unchanged as much as
|
||
possible and do your work in layers on top of the
|
||
core system.
|
||
Doing so gives you a greater level of portability when
|
||
upgrading to new versions of the core system or Board
|
||
Support Packages (BSPs).
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Share layers amongst the developers of a
|
||
particular project and contain the policy configuration
|
||
that defines the project.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Set up an Autobuilder:</emphasis>
|
||
Autobuilders are often the core of the development
|
||
environment.
|
||
It is here that changes from individual developers are brought
|
||
together and centrally tested and subsequent decisions about
|
||
releases can be made.
|
||
Autobuilders also allow for "continuous integration" style
|
||
testing of software components and regression identification
|
||
and tracking.</para>
|
||
|
||
<para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
|
||
for more information and links to buildbot.
|
||
The Yocto Project team has found this implementation
|
||
works well in this role.
|
||
A public example of this is the Yocto Project
|
||
Autobuilders, which we use to test the overall health of the
|
||
project.</para>
|
||
|
||
<para>The features of this system are:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
Highlights when commits break the build.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Populates an sstate cache from which
|
||
developers can pull rather than requiring local
|
||
builds.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Allows commit hook triggers,
|
||
which trigger builds when commits are made.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Allows triggering of automated image booting
|
||
and testing under the QuickEMUlator (QEMU).
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Supports incremental build testing and
|
||
from-scratch builds.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Shares output that allows developer
|
||
testing and historical regression investigation.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Creates output that can be used for releases.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Allows scheduling of builds so that resources
|
||
can be used efficiently.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Set up Test Machines:</emphasis>
|
||
Use a small number of shared, high performance systems
|
||
for testing purposes.
|
||
Developers can use these systems for wider, more
|
||
extensive testing while they continue to develop
|
||
locally using their primary development system.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Document Policies and Change Flow:</emphasis>
|
||
The Yocto Project itself uses a hierarchical structure and a
|
||
pull model.
|
||
Scripts exist to create and send pull requests
|
||
(i.e. <filename>create-pull-request</filename> and
|
||
<filename>send-pull-request</filename>).
|
||
This model is in line with other open source projects where
|
||
maintainers are responsible for specific areas of the project
|
||
and a single maintainer handles the final "top-of-tree" merges.
|
||
<note>
|
||
You can also use a more collective push model.
|
||
The <filename>gitolite</filename> software supports both the
|
||
push and pull models quite easily.
|
||
</note></para>
|
||
|
||
<para>As with any development environment, it is important
|
||
to document the policy used as well as any main project
|
||
guidelines so they are understood by everyone.
|
||
It is also a good idea to have well structured
|
||
commit messages, which are usually a part of a project's
|
||
guidelines.
|
||
Good commit messages are essential when looking back in time and
|
||
trying to understand why changes were made.</para>
|
||
|
||
<para>If you discover that changes are needed to the core
|
||
layer of the project, it is worth sharing those with the
|
||
community as soon as possible.
|
||
Chances are if you have discovered the need for changes,
|
||
someone else in the community needs them also.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Development Environment Summary:</emphasis>
|
||
Aside from the previous steps, some best practices exist
|
||
within the Yocto Project development environment.
|
||
Consider the following:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
Use <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>
|
||
as the source control system.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Maintain your Metadata in layers that make sense
|
||
for your situation.
|
||
See the "<link linkend='understanding-and-creating-layers'>Understanding
|
||
and Creating Layers</link>" section for more information on
|
||
layers.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Separate the project's Metadata and code by using
|
||
separate Git repositories.
|
||
See the
|
||
"<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
|
||
section for information on these repositories.
|
||
See the
|
||
"<link linkend='working-with-yocto-project-source-files'>Working With Yocto Project Source Files</link>"
|
||
section for information on how to set up local Git
|
||
repositories for related upstream Yocto Project
|
||
Git repositories.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Set up the directory for the shared state cache
|
||
(<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
|
||
where it makes sense.
|
||
For example, set up the sstate cache on a system used
|
||
by developers in the same organization and share the
|
||
same source directories on their machines.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Set up an Autobuilder and have it populate the
|
||
sstate cache and source directories.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
The Yocto Project community encourages you
|
||
to send patches to the project to fix bugs or add features.
|
||
If you do submit patches, follow the project commit
|
||
guidelines for writing good commit messages.
|
||
See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
|
||
section.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Send changes to the core sooner than later
|
||
as others are likely to run into the same issues.
|
||
For some guidance on mailing lists to use, see the list in the
|
||
"<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
|
||
section.
|
||
For a description of the available mailing lists, see the
|
||
"<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
|
||
section in the Yocto Project Reference Manual.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para></listitem>
|
||
</orderedlist>
|
||
</para>
|
||
</section>
|
||
|
||
<section id='submitting-a-defect-against-the-yocto-project'>
|
||
<title>Submitting a Defect Against the Yocto Project</title>
|
||
|
||
<para>
|
||
Use the Yocto Project implementation of
|
||
<ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink>
|
||
to submit a defect (bug) against the Yocto Project.
|
||
For additional information on this implementation of Bugzilla see the
|
||
"<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>"
|
||
section in the Yocto Project Reference Manual.
|
||
For more detail on any of the following steps, see the Yocto Project
|
||
<ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>.
|
||
</para>
|
||
|
||
<para>
|
||
Use the following general steps to submit a bug"
|
||
|
||
<orderedlist>
|
||
<listitem><para>
|
||
Open the Yocto Project implementation of
|
||
<ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Click "File a Bug" to enter a new bug.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Choose the appropriate "Classification", "Product", and
|
||
"Component" for which the bug was found.
|
||
Bugs for the Yocto Project fall into one of several
|
||
classifications, which in turn break down into several
|
||
products and components.
|
||
For example, for a bug against the
|
||
<filename>meta-intel</filename> layer, you would choose
|
||
"Build System, Metadata & Runtime", "BSPs", and
|
||
"bsps-meta-intel", respectively.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Choose the "Version" of the Yocto Project for which you found
|
||
the bug (e.g. &DISTRO;).
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Determine and select the "Severity" of the bug.
|
||
The severity indicates how the bug impacted your work.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Choose the "Hardware" that the bug impacts.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Choose the "Architecture" that the bug impacts.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Choose a "Documentation change" item for the bug.
|
||
Fixing a bug might or might not affect the Yocto Project
|
||
documentation.
|
||
If you are unsure of the impact to the documentation, select
|
||
"Don't Know".
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Provide a brief "Summary" of the bug.
|
||
Try to limit your summary to just a line or two and be sure
|
||
to capture the essence of the bug.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Provide a detailed "Description" of the bug.
|
||
You should provide as much detail as you can about the context,
|
||
behavior, output, and so forth that surrounds the bug.
|
||
You can even attach supporting files for output from logs by
|
||
using the "Add an attachment" button.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Click the "Submit Bug" button submit the bug.
|
||
A new Bugzilla number is assigned to the bug and the defect
|
||
is logged in the bug tracking system.
|
||
</para></listitem>
|
||
</orderedlist>
|
||
Once you file a bug, the bug is processed by the Yocto Project Bug
|
||
Triage Team and further details concerning the bug are assigned
|
||
(e.g. priority and owner).
|
||
You are the "Submitter" of the bug and any further categorization,
|
||
progress, or comments on the bug result in Bugzilla sending you an
|
||
automated email concerning the particular change or progress to the
|
||
bug.
|
||
</para>
|
||
</section>
|
||
|
||
<section id='how-to-submit-a-change'>
|
||
<title>Submitting a Change to the Yocto Project</title>
|
||
|
||
<para>
|
||
Contributions to the Yocto Project and OpenEmbedded are very welcome.
|
||
Because the system is extremely configurable and flexible, we recognize
|
||
that developers will want to extend, configure or optimize it for
|
||
their specific uses.
|
||
</para>
|
||
|
||
<para>
|
||
The Yocto Project uses a mailing list and a patch-based workflow
|
||
that is similar to the Linux kernel but contains important
|
||
differences.
|
||
In general, a mailing list exists through which you can submit
|
||
patches.
|
||
You should send patches to the appropriate mailing list so that they
|
||
can be reviewed and merged by the appropriate maintainer.
|
||
The specific mailing list you need to use depends on the
|
||
location of the code you are changing.
|
||
Each component (e.g. layer) should have a
|
||
<filename>README</filename> file that indicates where to send
|
||
the changes and which process to follow.
|
||
</para>
|
||
|
||
<para>
|
||
You can send the patch to the mailing list using whichever approach
|
||
you feel comfortable with to generate the patch.
|
||
Once sent, the patch is usually reviewed by the community at large.
|
||
If somebody has concerns with the patch, they will usually voice
|
||
their concern over the mailing list.
|
||
If a patch does not receive any negative reviews, the maintainer of
|
||
the affected layer typically takes the patch, tests it, and then
|
||
based on successful testing, merges the patch.
|
||
</para>
|
||
|
||
<para id='figuring-out-the-mailing-list-to-use'>
|
||
The "poky" repository, which is the Yocto Project's reference build
|
||
environment, is a hybrid repository that contains several
|
||
individual pieces (e.g. BitBake, Metadata, documentation,
|
||
and so forth) built using the combo-layer tool.
|
||
The upstream location used for submitting changes varies by
|
||
component:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<emphasis>Core Metadata:</emphasis>
|
||
Send your patch to the
|
||
<ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink>
|
||
mailing list. For example, a change to anything under
|
||
the <filename>meta</filename> or
|
||
<filename>scripts</filename> directories should be sent
|
||
to this mailing list.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>BitBake:</emphasis>
|
||
For changes to BitBake (i.e. anything under the
|
||
<filename>bitbake</filename> directory), send your patch
|
||
to the
|
||
<ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink>
|
||
mailing list.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>"meta-*" trees:</emphasis>
|
||
These trees contain Metadata.
|
||
Use the
|
||
<ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink>
|
||
mailing list.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<para>
|
||
For changes to other layers hosted in the Yocto Project source
|
||
repositories (i.e. <filename>yoctoproject.org</filename>), tools,
|
||
and the Yocto Project documentation, use the
|
||
<ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink>
|
||
general mailing list.
|
||
<note>
|
||
Sometimes a layer's documentation specifies to use a
|
||
particular mailing list.
|
||
If so, use that list.
|
||
</note>
|
||
For additional recipes that do not fit into the core Metadata, you
|
||
should determine which layer the recipe should go into and submit
|
||
the change in the manner recommended by the documentation (e.g.
|
||
the <filename>README</filename> file) supplied with the layer.
|
||
If in doubt, please ask on the Yocto general mailing list or on
|
||
the openembedded-devel mailing list.
|
||
</para>
|
||
|
||
<para>
|
||
You can also push a change upstream and request a maintainer to
|
||
pull the change into the component's upstream repository.
|
||
You do this by pushing to a contribution repository that is upstream.
|
||
See the
|
||
"<ulink url='&YOCTO_DOCS_REF_URL;#workflows'>Workflows</ulink>"
|
||
section in the Yocto Project Reference Manual for additional
|
||
concepts on working in the Yocto Project development environment.
|
||
</para>
|
||
|
||
<para>
|
||
Two commonly used testing repositories exist for
|
||
OpenEmbedded-Core:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<emphasis>"ross/mut" branch:</emphasis>
|
||
The "mut" (master-under-test) tree
|
||
exists in the <filename>poky-contrib</filename> repository
|
||
in the
|
||
<ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>"master-next" branch:</emphasis>
|
||
This branch is part of the main
|
||
"poky" repository in the Yocto Project source repositories.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
Maintainers use these branches to test submissions prior to merging
|
||
patches.
|
||
Thus, you can get an idea of the status of a patch based on
|
||
whether the patch has been merged into one of these branches.
|
||
<note>
|
||
This system is imperfect and changes can sometimes get lost in the
|
||
flow.
|
||
Asking about the status of a patch or change is reasonable if the
|
||
change has been idle for a while with no feedback.
|
||
The Yocto Project does have plans to use
|
||
<ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink>
|
||
to track the status of patches and also to automatically preview
|
||
patches.
|
||
</note>
|
||
</para>
|
||
|
||
<para>
|
||
The following sections provide procedures for submitting a change.
|
||
</para>
|
||
|
||
<section id='pushing-a-change-upstream'>
|
||
<title>Using Scripts to Push a Change Upstream and Request a Pull</title>
|
||
|
||
<para>
|
||
Follow this procedure to push a change to an upstream "contrib"
|
||
Git repository:
|
||
<note>
|
||
You can find general Git information on how to push a change
|
||
upstream in the
|
||
<ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>.
|
||
</note>
|
||
<orderedlist>
|
||
<listitem><para>
|
||
<emphasis>Make Your Changes Locally:</emphasis>
|
||
Make your changes in your local Git repository.
|
||
You should make small, controlled, isolated changes.
|
||
Keeping changes small and isolated aids review,
|
||
makes merging/rebasing easier and keeps the change
|
||
history clean should anyone need to refer to it in
|
||
future.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Stage Your Changes:</emphasis>
|
||
Stage your changes by using the <filename>git add</filename>
|
||
command on each file you changed.
|
||
</para></listitem>
|
||
<listitem><para id='making-sure-you-have-correct-commit-information'>
|
||
<emphasis>Commit Your Changes:</emphasis>
|
||
Commit the change by using the
|
||
<filename>git commit</filename> command.
|
||
Make sure your commit information follows standards by
|
||
following these accepted conventions:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
Be sure to include a "Signed-off-by:" line in the
|
||
same style as required by the Linux kernel.
|
||
Adding this line signifies that you, the submitter,
|
||
have agreed to the Developer's Certificate of
|
||
Origin 1.1 as follows:
|
||
<literallayout class='monospaced'>
|
||
Developer's Certificate of Origin 1.1
|
||
|
||
By making a contribution to this project, I certify that:
|
||
|
||
(a) The contribution was created in whole or in part by me and I
|
||
have the right to submit it under the open source license
|
||
indicated in the file; or
|
||
|
||
(b) The contribution is based upon previous work that, to the best
|
||
of my knowledge, is covered under an appropriate open source
|
||
license and I have the right under that license to submit that
|
||
work with modifications, whether created in whole or in part
|
||
by me, under the same open source license (unless I am
|
||
permitted to submit under a different license), as indicated
|
||
in the file; or
|
||
|
||
(c) The contribution was provided directly to me by some other
|
||
person who certified (a), (b) or (c) and I have not modified
|
||
it.
|
||
|
||
(d) I understand and agree that this project and the contribution
|
||
are public and that a record of the contribution (including all
|
||
personal information I submit with it, including my sign-off) is
|
||
maintained indefinitely and may be redistributed consistent with
|
||
this project or the open source license(s) involved.
|
||
</literallayout>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Provide a single-line summary of the change.
|
||
and,
|
||
if more explanation is needed, provide more
|
||
detail in the body of the commit.
|
||
This summary is typically viewable in the
|
||
"shortlist" of changes.
|
||
Thus, providing something short and descriptive
|
||
that gives the reader a summary of the change is
|
||
useful when viewing a list of many commits.
|
||
You should prefix this short description with the
|
||
recipe name (if changing a recipe), or else with
|
||
the short form path to the file being changed.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
For the body of the commit message, provide
|
||
detailed information that describes what you
|
||
changed, why you made the change, and the approach
|
||
you used.
|
||
It might also be helpful if you mention how you
|
||
tested the change.
|
||
Provide as much detail as you can in the body of
|
||
the commit message.
|
||
<note>
|
||
You do not need to provide a more detailed
|
||
explanation of a change if the change is
|
||
minor to the point of the single line
|
||
summary providing all the information.
|
||
</note>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
If the change addresses a specific bug or issue
|
||
that is associated with a bug-tracking ID,
|
||
include a reference to that ID in your detailed
|
||
description.
|
||
For example, the Yocto Project uses a specific
|
||
convention for bug references - any commit that
|
||
addresses a specific bug should use the following
|
||
form for the detailed description.
|
||
Be sure to use the actual bug-tracking ID from
|
||
Bugzilla for
|
||
<replaceable>bug-id</replaceable>:
|
||
<literallayout class='monospaced'>
|
||
Fixes [YOCTO #<replaceable>bug-id</replaceable>]
|
||
|
||
<replaceable>detailed description of change</replaceable>
|
||
</literallayout>
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis>
|
||
If you have arranged for permissions to push to an
|
||
upstream contrib repository, push the change to that
|
||
repository:
|
||
<literallayout class='monospaced'>
|
||
$ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable>
|
||
</literallayout>
|
||
For example, suppose you have permissions to push into the
|
||
upstream <filename>meta-intel-contrib</filename>
|
||
repository and you are working in a local branch named
|
||
<replaceable>your_name</replaceable><filename>/README</filename>.
|
||
The following command pushes your local commits to the
|
||
<filename>meta-intel-contrib</filename> upstream
|
||
repository and puts the commit in a branch named
|
||
<replaceable>your_name</replaceable><filename>/README</filename>:
|
||
<literallayout class='monospaced'>
|
||
$ git push meta-intel-contrib <replaceable>your_name</replaceable>/README
|
||
</literallayout>
|
||
</para></listitem>
|
||
<listitem><para id='push-determine-who-to-notify'>
|
||
<emphasis>Determine Who to Notify:</emphasis>
|
||
Determine the maintainer or the mailing list
|
||
that you need to notify for the change.</para>
|
||
|
||
<para>Before submitting any change, you need to be sure
|
||
who the maintainer is or what mailing list that you need
|
||
to notify.
|
||
Use either these methods to find out:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
<emphasis>Maintenance File:</emphasis>
|
||
Examine the <filename>maintainers.inc</filename>
|
||
file, which is located in the
|
||
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
|
||
at
|
||
<filename>meta/conf/distro/include</filename>,
|
||
to see who is responsible for code.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Search by File:</emphasis>
|
||
Using <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>,
|
||
you can enter the following command to bring up a
|
||
short list of all commits against a specific file:
|
||
<literallayout class='monospaced'>
|
||
git shortlog -- <replaceable>filename</replaceable>
|
||
</literallayout>
|
||
Just provide the name of the file for which you
|
||
are interested.
|
||
The information returned is not ordered by history
|
||
but does include a list of everyone who has
|
||
committed grouped by name.
|
||
From the list, you can see who is responsible for
|
||
the bulk of the changes against the file.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Examine the List of Mailing Lists:</emphasis>
|
||
For a list of the Yocto Project and related mailing
|
||
lists, see the
|
||
"<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
|
||
section in the Yocto Project Reference Manual.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Make a Pull Request:</emphasis>
|
||
Notify the maintainer or the mailing list that you have
|
||
pushed a change by making a pull request.</para>
|
||
|
||
<para>The Yocto Project provides two scripts that
|
||
conveniently let you generate and send pull requests to the
|
||
Yocto Project.
|
||
These scripts are <filename>create-pull-request</filename>
|
||
and <filename>send-pull-request</filename>.
|
||
You can find these scripts in the
|
||
<filename>scripts</filename> directory within the
|
||
<ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
|
||
(e.g. <filename>~/poky/scripts</filename>).
|
||
</para>
|
||
|
||
<para>Using these scripts correctly formats the requests
|
||
without introducing any whitespace or HTML formatting.
|
||
The maintainer that receives your patches either directly
|
||
or through the mailing list needs to be able to save and
|
||
apply them directly from your emails.
|
||
Using these scripts is the preferred method for sending
|
||
patches.</para>
|
||
|
||
<para>First, create the pull request.
|
||
For example, the following command runs the script,
|
||
specifies the upstream repository in the contrib directory
|
||
into which you pushed the change, and provides a subject
|
||
line in the created patch files:
|
||
<literallayout class='monospaced'>
|
||
$ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README"
|
||
</literallayout>
|
||
Running this script forms
|
||
<filename>*.patch</filename> files in a folder named
|
||
<filename>pull-</filename><replaceable>PID</replaceable>
|
||
in the current directory.
|
||
One of the patch files is a cover letter.</para>
|
||
|
||
<para>Before running the
|
||
<filename>send-pull-request</filename> script, you must
|
||
edit the cover letter patch to insert information about
|
||
your change.
|
||
After editing the cover letter, send the pull request.
|
||
For example, the following command runs the script and
|
||
specifies the patch directory and email address.
|
||
In this example, the email address is a mailing list:
|
||
<literallayout class='monospaced'>
|
||
$ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org
|
||
</literallayout>
|
||
You need to follow the prompts as the script is
|
||
interactive.
|
||
<note>
|
||
For help on using these scripts, simply provide the
|
||
<filename>-h</filename> argument as follows:
|
||
<literallayout class='monospaced'>
|
||
$ poky/scripts/create-pull-request -h
|
||
$ poky/scripts/send-pull-request -h
|
||
</literallayout>
|
||
</note>
|
||
</para></listitem>
|
||
</orderedlist>
|
||
</para>
|
||
</section>
|
||
|
||
<section id='submitting-a-patch'>
|
||
<title>Using Email to Submit a Patch</title>
|
||
|
||
<para>
|
||
You can submit patches without using the
|
||
<filename>create-pull-request</filename> and
|
||
<filename>send-pull-request</filename> scripts described in the
|
||
previous section.
|
||
However, keep in mind, the preferred method is to use the scripts.
|
||
</para>
|
||
|
||
<para>
|
||
Depending on the components changed, you need to submit the email
|
||
to a specific mailing list.
|
||
For some guidance on which mailing list to use, see the
|
||
<link linkend='figuring-out-the-mailing-list-to-use'>beginning</link>
|
||
of this section.
|
||
For a description of all the available mailing lists, see the
|
||
"<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
|
||
section in the Yocto Project Reference Manual.
|
||
</para>
|
||
|
||
<para>
|
||
Here is the general procedure on how to submit a patch through
|
||
email without using the scripts:
|
||
<orderedlist>
|
||
<listitem><para>
|
||
<emphasis>Make Your Changes Locally:</emphasis>
|
||
Make your changes in your local Git repository.
|
||
You should make small, controlled, isolated changes.
|
||
Keeping changes small and isolated aids review,
|
||
makes merging/rebasing easier and keeps the change
|
||
history clean should anyone need to refer to it in
|
||
future.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Stage Your Changes:</emphasis>
|
||
Stage your changes by using the <filename>git add</filename>
|
||
command on each file you changed.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Commit Your Changes:</emphasis>
|
||
Commit the change by using the
|
||
<filename>git commit --signoff</filename> command.
|
||
Using the <filename>--signoff</filename> option identifies
|
||
you as the person making the change and also satisfies
|
||
the Developer's Certificate of Origin (DCO) shown earlier.
|
||
</para>
|
||
|
||
<para>When you form a commit, you must follow certain
|
||
standards established by the Yocto Project development
|
||
team.
|
||
See
|
||
<link linkend='making-sure-you-have-correct-commit-information'>Step 3</link>
|
||
in the previous section for information on how to
|
||
provide commit information that meets Yocto Project
|
||
commit message standards.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Format the Commit:</emphasis>
|
||
Format the commit into an email message.
|
||
To format commits, use the
|
||
<filename>git format-patch</filename> command.
|
||
When you provide the command, you must include a revision
|
||
list or a number of patches as part of the command.
|
||
For example, either of these two commands takes your most
|
||
recent single commit and formats it as an email message in
|
||
the current directory:
|
||
<literallayout class='monospaced'>
|
||
$ git format-patch -1
|
||
</literallayout>
|
||
or
|
||
<literallayout class='monospaced'>
|
||
$ git format-patch HEAD~
|
||
</literallayout></para>
|
||
|
||
<para>After the command is run, the current directory
|
||
contains a numbered <filename>.patch</filename> file for
|
||
the commit.</para>
|
||
|
||
<para>If you provide several commits as part of the
|
||
command, the <filename>git format-patch</filename> command
|
||
produces a series of numbered files in the current
|
||
directory – one for each commit.
|
||
If you have more than one patch, you should also use the
|
||
<filename>--cover</filename> option with the command,
|
||
which generates a cover letter as the first "patch" in
|
||
the series.
|
||
You can then edit the cover letter to provide a
|
||
description for the series of patches.
|
||
For information on the
|
||
<filename>git format-patch</filename> command,
|
||
see <filename>GIT_FORMAT_PATCH(1)</filename> displayed
|
||
using the <filename>man git-format-patch</filename>
|
||
command.
|
||
<note>
|
||
If you are or will be a frequent contributor to the
|
||
Yocto Project or to OpenEmbedded, you might consider
|
||
requesting a contrib area and the necessary associated
|
||
rights.
|
||
</note>
|
||
</para></listitem>
|
||
<listitem><para>
|
||
<emphasis>Import the Files Into Your Mail Client:</emphasis>
|
||
Import the files into your mail client by using the
|
||
<filename>git send-email</filename> command.
|
||
<note>
|
||
In order to use <filename>git send-email</filename>,
|
||
you must have the proper Git packages installed on
|
||
your host.
|
||
For Ubuntu, Debian, and Fedora the package is
|
||
<filename>git-email</filename>.
|
||
</note></para>
|
||
|
||
<para>The <filename>git send-email</filename> command
|
||
sends email by using a local or remote Mail Transport Agent
|
||
(MTA) such as <filename>msmtp</filename>,
|
||
<filename>sendmail</filename>, or through a direct
|
||
<filename>smtp</filename> configuration in your Git
|
||
<filename>~/.gitconfig</filename> file.
|
||
If you are submitting patches through email only, it is
|
||
very important that you submit them without any whitespace
|
||
or HTML formatting that either you or your mailer
|
||
introduces.
|
||
The maintainer that receives your patches needs to be able
|
||
to save and apply them directly from your emails.
|
||
A good way to verify that what you are sending will be
|
||
applicable by the maintainer is to do a dry run and send
|
||
them to yourself and then save and apply them as the
|
||
maintainer would.</para>
|
||
|
||
<para>The <filename>git send-email</filename> command is
|
||
the preferred method for sending your patches using
|
||
email since there is no risk of compromising whitespace
|
||
in the body of the message, which can occur when you use
|
||
your own mail client.
|
||
The command also has several options that let you
|
||
specify recipients and perform further editing of the
|
||
email message.
|
||
For information on how to use the
|
||
<filename>git send-email</filename> command,
|
||
see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
|
||
the <filename>man git-send-email</filename> command.
|
||
</para></listitem>
|
||
</orderedlist>
|
||
</para>
|
||
</section>
|
||
</section>
|
||
</chapter>
|
||
<!--
|
||
vim: expandtab tw=80 ts=4
|
||
-->
|