mirror of
https://git.yoctoproject.org/poky
synced 2026-09-14 21:49:33 +02:00
dev-manual: Removed "newbie" chapter.
This chapter only had the stuff about submitting a defect against YP and making a change to YP. I moved that information into the common tasks chapter as it is "how-to" information. Removal of this chapter alse required that the mega-manual.xml file be updated to not include the chapter. (From yocto-docs rev: 4421b1585c21a6f7862525ba972f7e765626066e) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
committed by
Richard Purdie
Richard Purdie
parent
9a37a3d568
commit
368474d740
@@ -13783,6 +13783,633 @@
|
|||||||
</section>
|
</section>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
<section id='making-changes-to-the-yocto-project'>
|
||||||
|
<title>Making Changes to the Yocto Project</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Because the Yocto Project is an open-source, community-based
|
||||||
|
project, you can effect changes to the project.
|
||||||
|
This section presents procedures that show you how to submit
|
||||||
|
a defect against the project and how to submit a change.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<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_OM_URL;#gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</ulink>"
|
||||||
|
section in the Yocto Project Overview and Concepts 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_OM_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'>list</link>
|
||||||
|
at the beginning 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>
|
||||||
|
</section>
|
||||||
|
|
||||||
<section id='working-with-licenses'>
|
<section id='working-with-licenses'>
|
||||||
<title>Working With Licenses</title>
|
<title>Working With Licenses</title>
|
||||||
|
|
||||||
|
|||||||
@@ -1,627 +0,0 @@
|
|||||||
<!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='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_OM_URL;#gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</ulink>"
|
|
||||||
section in the Yocto Project Overview and Concepts 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_OM_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'>list</link>
|
|
||||||
at the beginning 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
|
|
||||||
-->
|
|
||||||
@@ -168,8 +168,6 @@
|
|||||||
|
|
||||||
<xi:include href="dev-manual-start.xml"/>
|
<xi:include href="dev-manual-start.xml"/>
|
||||||
|
|
||||||
<xi:include href="dev-manual-newbie.xml"/>
|
|
||||||
|
|
||||||
<xi:include href="dev-manual-common-tasks.xml"/>
|
<xi:include href="dev-manual-common-tasks.xml"/>
|
||||||
|
|
||||||
<xi:include href="dev-manual-qemu.xml"/>
|
<xi:include href="dev-manual-qemu.xml"/>
|
||||||
|
|||||||
@@ -169,8 +169,6 @@
|
|||||||
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-intro.xml"/>
|
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-intro.xml"/>
|
||||||
<xi:include
|
<xi:include
|
||||||
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-start.xml"/>
|
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-start.xml"/>
|
||||||
<xi:include
|
|
||||||
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-newbie.xml"/>
|
|
||||||
<xi:include
|
<xi:include
|
||||||
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-common-tasks.xml"/>
|
xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-common-tasks.xml"/>
|
||||||
<xi:include
|
<xi:include
|
||||||
|
|||||||
Reference in New Issue
Block a user