mirror of
https://git.yoctoproject.org/poky
synced 2026-05-09 17:39:31 +00:00
Scott Rifenbark
fcb53beee4
Fixes [YOCTO #11630] The "Git" section in the dev-manual is really about concepts. There are a couple of examples that might or not might be allowed to ultimately stay. I have moved the section to the ref-manual. If those examples get replicated in the new dev-manual, I will update the "Git" section further. For now, however, these remain in this moved section. (From yocto-docs rev: 2e4b87fdab29c13ce0d2314e50c93e37404b6f7e) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
904 lines
45 KiB
XML
904 lines
45 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>Using the Yocto Project in a Team Environment</title>
|
||
|
||
<para>
|
||
It might not be immediately clear how you can use the Yocto
|
||
Project in a team 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 with these types of situations, this section presents
|
||
some of the project's most successful experiences,
|
||
practices, solutions, and available technologies that work well.
|
||
Keep in mind, the information here is a starting point.
|
||
You can build off it and customize it to fit any
|
||
particular working environment and set of practices.
|
||
</para>
|
||
|
||
<section id='best-practices-system-configurations'>
|
||
<title>System Configurations</title>
|
||
|
||
<para>
|
||
Systems across a large team should meet the needs of
|
||
two types of developers: those working on the contents of the
|
||
operating system image itself and those developing applications.
|
||
Regardless of the type of developer, their workstations must
|
||
be both reasonably powerful and run Linux.
|
||
</para>
|
||
|
||
<section id='best-practices-application-development'>
|
||
<title>Application Development</title>
|
||
|
||
<para>
|
||
For developers who mainly do application level work
|
||
on top of an existing software stack,
|
||
the following list shows practices that work best.
|
||
For information on using a Software Development Kit (SDK), see
|
||
the
|
||
<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>:
|
||
<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 Software Development Kit (SDK) Developer's Guide</ulink>".
|
||
</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>
|
||
</section>
|
||
|
||
<section id='best-practices-core-system-development'>
|
||
<title>Core System Development</title>
|
||
|
||
<para>
|
||
For core system development, it is often best to have the
|
||
build system itself available on the developer workstations
|
||
so developers can run their own builds and directly
|
||
rebuild the software stack.
|
||
You should 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).
|
||
You can share layers amongst the developers of a particular
|
||
project and contain the policy configuration that defines
|
||
the project.
|
||
</para>
|
||
|
||
<para>
|
||
Aside from the previous best practices, there exists a number
|
||
of tips and tricks that can help speed up core development
|
||
projects:
|
||
<itemizedlist>
|
||
<listitem><para>Use a
|
||
<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>
|
||
(sstate) among groups of developers who are on a
|
||
fast network.
|
||
The best way to share sstate is through a
|
||
Network File System (NFS) share.
|
||
The first user to build a given component for the
|
||
first time contributes that object to the sstate,
|
||
while subsequent builds from other developers then
|
||
reuse the object rather than rebuild it themselves.
|
||
</para>
|
||
<para>Although it is possible to use other protocols for the
|
||
sstate such as HTTP and FTP, you should avoid these.
|
||
Using HTTP limits the sstate to read-only and
|
||
FTP provides poor performance.
|
||
</para></listitem>
|
||
<listitem><para>Have autobuilders contribute to the sstate
|
||
pool similarly to how the developer workstations
|
||
contribute.
|
||
For information, see the
|
||
"<link linkend='best-practices-autobuilders'>Autobuilders</link>"
|
||
section.</para></listitem>
|
||
<listitem><para>Build stand-alone tarballs that contain
|
||
"missing" system requirements if for some reason
|
||
developer workstations do not meet minimum system
|
||
requirements such as latest Python versions,
|
||
<filename>chrpath</filename>, or other tools.
|
||
You can install and relocate the tarball exactly as you
|
||
would the usual cross-development toolchain so that
|
||
all developers can meet minimum version requirements
|
||
on most distributions.</para></listitem>
|
||
<listitem><para>Use a small number of shared,
|
||
high performance systems for testing purposes
|
||
(e.g. dual, six-core Xeons with 24 Gbytes of RAM
|
||
and plenty of disk space).
|
||
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>Enable the PR Service when package feeds
|
||
need to be incremental with continually increasing
|
||
<ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink>
|
||
values.
|
||
Typically, this situation occurs when you use or
|
||
publish package feeds and use a shared state.
|
||
You should enable the PR Service for all users who
|
||
use the shared state pool.
|
||
For more information on the PR Service, see the
|
||
"<link linkend='working-with-a-pr-service'>Working With a PR Service</link>".
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</section>
|
||
</section>
|
||
|
||
<section id='best-practices-source-control-management'>
|
||
<title>Source Control Management (SCM)</title>
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
<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>
|
||
</section>
|
||
|
||
<section id='best-practices-autobuilders'>
|
||
<title>Autobuilders</title>
|
||
|
||
<para>
|
||
Autobuilders are often the core of a development project.
|
||
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>
|
||
</section>
|
||
|
||
<section id='best-practices-policies-and-change-flow'>
|
||
<title>Policies and Change Flow</title>
|
||
|
||
<para>
|
||
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.
|
||
</para>
|
||
|
||
<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>
|
||
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>
|
||
</section>
|
||
|
||
<section id='best-practices-summary'>
|
||
<title>Summary</title>
|
||
|
||
<para>
|
||
This section summarizes the key recommendations described in the
|
||
previous sections:
|
||
<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='getting-setup'>Getting Set Up</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'>How to Submit a Change</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'>How to Submit a Change</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>
|
||
</section>
|
||
</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>How to Submit a Change</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.
|
||
You should send patches to the appropriate mailing list so that they
|
||
can be reviewed and merged by the appropriate maintainer.
|
||
</para>
|
||
|
||
<section id='submit-change-overview'>
|
||
<title>Overview</title>
|
||
|
||
<para>
|
||
The Yocto Project uses a mailing list and 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.
|
||
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>
|
||
Specific to OpenEmbedded-Core, two commonly used testing trees
|
||
exist:
|
||
<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.
|
||
</para>
|
||
|
||
<para>
|
||
This system is imperfect and patches can sometimes get lost in the
|
||
flow.
|
||
Asking about the status of a patch is reasonable if the patch
|
||
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.
|
||
</para>
|
||
|
||
<para>
|
||
The following sections provide general instructions for both
|
||
pushing changes upstream and for submitting changes as patches.
|
||
</para>
|
||
</section>
|
||
|
||
<section id='submit-change-submissions-to-poky'>
|
||
<title>Submissions to Poky</title>
|
||
|
||
<para>
|
||
The "poky" repository, which is the Yocto Project's reference build
|
||
environment, is a hybrid repository that contains several
|
||
individual pieces (e.g. BitBake, OpenEmbedded-Core, meta-yocto,
|
||
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-yocto-bsp" and "meta-poky" trees:</emphasis>
|
||
These trees are
|
||
part of the "meta-yocto" repository in the Yocto Project
|
||
source repositories.
|
||
Use the
|
||
<ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink>
|
||
mailing list.
|
||
</para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</section>
|
||
|
||
<section id='submit-change-submissions-to-other-layers'>
|
||
<title>Submissions to Other Layers</title>
|
||
|
||
<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>
|
||
</section>
|
||
|
||
<section id='submit-change-patch-submission-details'>
|
||
<title>Patch Submission Details</title>
|
||
|
||
<para>
|
||
When submitting any change, you can check who you should be
|
||
notifying.
|
||
Use either of 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-poky/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>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<para>
|
||
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>
|
||
|
||
<para>
|
||
When you send a patch, 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>
|
||
|
||
<para>
|
||
In a collaborative environment, it is necessary to have some sort
|
||
of standard or method through which you submit changes.
|
||
Otherwise, things could get quite chaotic.
|
||
One general practice to follow is to make small, controlled 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>
|
||
|
||
<para>
|
||
When you make a commit, you must follow certain standards
|
||
established by the OpenEmbedded and Yocto Project development teams.
|
||
For each commit, you must provide a single-line summary of the
|
||
change and you should almost always provide a more detailed
|
||
description of what you did (i.e. the body of the commit message).
|
||
The only exceptions for not providing a detailed description would
|
||
be if your change is a simple, self-explanatory change that needs
|
||
no further description beyond the summary.
|
||
Here are the guidelines for composing a commit message:
|
||
<itemizedlist>
|
||
<listitem><para>
|
||
Provide a single-line, short summary of the change.
|
||
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.
|
||
</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:
|
||
<literallayout class='monospaced'>
|
||
Fixes [YOCTO #<replaceable>bug-id</replaceable>]
|
||
|
||
<replaceable>detailed description of change</replaceable>
|
||
</literallayout>
|
||
</para></listitem>
|
||
Where <replaceable>bug-id</replaceable> is replaced with the
|
||
specific bug ID from the Yocto Project Bugzilla instance.
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<para>
|
||
You can find more guidance on creating well-formed commit messages
|
||
at this OpenEmbedded wiki page:
|
||
<ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>.
|
||
</para>
|
||
</section>
|
||
|
||
<section id='pushing-a-change-upstream'>
|
||
<title>Using Scripts to Push a Change Upstream and Request a Pull</title>
|
||
|
||
<para>
|
||
The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
|
||
<itemizedlist>
|
||
<listitem><para>Make your changes in your local Git repository.</para></listitem>
|
||
<listitem><para>Stage your changes by using the <filename>git add</filename>
|
||
command on each file you changed.</para></listitem>
|
||
<listitem><para>
|
||
Commit the change by using the
|
||
<filename>git commit</filename> command.
|
||
Be sure to provide a commit message that follows the
|
||
project’s commit message standards as described earlier.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Push the change to the upstream "contrib" repository by
|
||
using the <filename>git push</filename> command.
|
||
</para></listitem>
|
||
<listitem><para>Notify the maintainer that you have pushed a change by making a pull
|
||
request.
|
||
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>.</para>
|
||
<para>Using these scripts correctly formats the requests without introducing any
|
||
whitespace or HTML formatting.
|
||
The maintainer that receives your patches 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>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></para></listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<para>
|
||
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>.
|
||
</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 list in the
|
||
"<link linkend='how-to-submit-a-change'>How to Submit a Change</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>
|
||
|
||
<para>
|
||
Here is the general procedure on how to submit a patch through email without using the
|
||
scripts:
|
||
<orderedlist>
|
||
<listitem><para>
|
||
Make your changes in your local Git repository.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
Stage your changes by using the
|
||
<filename>git add</filename> command on each file you
|
||
changed.
|
||
</para></listitem>
|
||
<listitem><para>
|
||
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 the earlier section
|
||
"<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
|
||
for Yocto Project commit message standards.
|
||
</para></listitem>
|
||
<listitem><para>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>
|
||
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 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
|
||
-->
|