sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

dev-manual: Read-through edits to Chapter 3. 

The changes are a result of a detailed read-through prior to
releasing YP 1.6.  The changes are varied and random.

(From yocto-docs rev: 04c09abf96a04c3ffeea8cdf7be8e1bb1b9055c6)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2014-03-17 14:36:17 -06:00 committed by Richard Purdie
parent cee847acf0
commit dd72756230
1 changed files with 159 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

263
documentation/dev-manual/dev-manual-newbie.xml
View File

@ -171,7 +171,7 @@
pool similarly to how the developer workstations pool similarly to how the developer workstations
contribute. contribute.
For information, see the For information, see the
<link linkend='best-practices-autobuilders'>Autobuilders</link> "<link linkend='best-practices-autobuilders'>Autobuilders</link>"
section.</para></listitem> section.</para></listitem>
<listitem><para>Build stand-alone tarballs that contain <listitem><para>Build stand-alone tarballs that contain
"missing" system requirements if for some reason "missing" system requirements if for some reason
@ -184,8 +184,8 @@
on most distributions.</para></listitem> on most distributions.</para></listitem>
<listitem><para>Use a small number of shared, <listitem><para>Use a small number of shared,
high performance systems for testing purposes high performance systems for testing purposes
(e.g. dual six core Xeons with 24GB RAM and plenty of (e.g. dual, six-core Xeons with 24 Gbytes of RAM
disk space). and plenty of disk space).
Developers can use these systems for wider, more Developers can use these systems for wider, more
extensive testing while they continue to develop extensive testing while they continue to develop
locally using their primary development system. locally using their primary development system.
@ -222,10 +222,8 @@
allows you to work remotely, and then connects back to the allows you to work remotely, and then connects back to the
infrastructure. infrastructure.
<note> <note>
For information about BitBake and SCMs, see the For information about BitBake, see the
BitBake manual located in the <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
<filename>bitbake/doc/manual</filename> directory of the
<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
</note> </note>
</para> </para>
@ -238,7 +236,7 @@
being used to generate the web interface that lets you view the being used to generate the web interface that lets you view the
repositories. repositories.
The <filename>gitolite</filename> software identifies users The <filename>gitolite</filename> software identifies users
using <filename>ssh</filename> keys and allows branch-based using SSH keys and allows branch-based
access controls to repositories that you can control as little access controls to repositories that you can control as little
or as much as necessary. or as much as necessary.
</para> </para>
@ -298,8 +296,8 @@
<listitem><para>Allows triggering of automated image booting <listitem><para>Allows triggering of automated image booting
and testing under the QuickEMUlator (QEMU). and testing under the QuickEMUlator (QEMU).
</para></listitem> </para></listitem>
<listitem><para>Supports incremental build testing and from <listitem><para>Supports incremental build testing and
scratch builds.</para></listitem> from-scratch builds.</para></listitem>
<listitem><para>Shares output that allows developer <listitem><para>Shares output that allows developer
testing and historical regression investigation. testing and historical regression investigation.
</para></listitem> </para></listitem>
@ -365,14 +363,18 @@
See the "<link linkend='understanding-and-creating-layers'>Understanding See the "<link linkend='understanding-and-creating-layers'>Understanding
and Creating Layers</link>" section for more information on and Creating Layers</link>" section for more information on
layers.</para></listitem> layers.</para></listitem>
<listitem><para>Separate the project's Metadata and code by using <listitem><para>
Separate the project's Metadata and code by using
separate Git repositories. separate Git repositories.
See the "<link linkend='yocto-project-repositories'>Yocto Project See the
Source Repositories</link>" section for information on these "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>"
repositories. section for information on these repositories.
See the "<link linkend='getting-setup'>Getting Set Up</link>" section See the
for information on how to set up various Yocto Project related "<link linkend='getting-setup'>Getting Set Up</link>"
Git repositories.</para></listitem> 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 <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>) (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
where it makes sense. where it makes sense.
@ -389,7 +391,7 @@
See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
section.</para></listitem> section.</para></listitem>
<listitem><para>Send changes to the core sooner than later <listitem><para>Send changes to the core sooner than later
as others likely run into the same issues. as others are likely to run into the same issues.
For some guidance on mailing lists to use, see the list in the 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>" "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
section. section.
@ -415,7 +417,9 @@
From the interface, you can click on any particular item in the "Name" From the interface, you can click on any particular item in the "Name"
column and see the URL at the bottom of the page that you need to clone column and see the URL at the bottom of the page that you need to clone
a Git repository for that particular item. a Git repository for that particular item.
Having a local Git repository of the Source Directory (poky) allows Having a local Git repository of the
<link linkend='source-directory'>Source Directory</link>, which is
usually named "poky", allows
you to make changes, contribute to the history, and ultimately enhance you to make changes, contribute to the history, and ultimately enhance
the Yocto Project's tools, Board Support Packages, and so forth. the Yocto Project's tools, Board Support Packages, and so forth.
</para> </para>
@ -447,9 +451,9 @@
<imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
</para></listitem> </para></listitem>
<listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis> <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis>
This area contains index releases such as This is an index of releases such as
the <trademark class='trade'>Eclipse</trademark> the <trademark class='trade'>Eclipse</trademark>
Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains, Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers for cross-development toolchains,
and all released versions of Yocto Project in the form of images or tarballs. and all released versions of Yocto Project in the form of images or tarballs.
Downloading and extracting these files does not produce a local copy of the Downloading and extracting these files does not produce a local copy of the
Git repository but rather a snapshot of a particular release or image.</para> Git repository but rather a snapshot of a particular release or image.</para>
@ -494,11 +498,11 @@
"<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section. "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section.
</para></listitem> </para></listitem>
<listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis> <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
The task executor and scheduler used by The task executor and scheduler used by the OpenEmbedded build
the OpenEmbedded build system to build images. system to build images.
For more information on BitBake, see the BitBake documentation For more information on BitBake, see the
in the <filename>bitbake/doc/manual</filename> directory of the <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
<link linkend='source-directory'>Source Directory</link>.</para></listitem> </para></listitem>
<listitem> <listitem>
<para id='build-directory'><emphasis>Build Directory:</emphasis> <para id='build-directory'><emphasis>Build Directory:</emphasis>
This term refers to the area used by the OpenEmbedded build system for builds. This term refers to the area used by the OpenEmbedded build system for builds.
@ -533,8 +537,9 @@
$ cd $HOME $ cd $HOME
$ source poky/&OE_INIT_FILE; test-builds $ source poky/&OE_INIT_FILE; test-builds
</literallayout></para></listitem> </literallayout></para></listitem>
<listitem><para>Provide a directory path and <listitem><para>
specifically name the build directory. Provide a directory path and
specifically name the Build Directory.
Any intermediate folders in the pathname must Any intermediate folders in the pathname must
exist. exist.
This next example creates a Build Directory named This next example creates a Build Directory named
@ -557,23 +562,31 @@
<listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
and inheritance so that commonly used patterns can be defined once and then easily used and inheritance so that commonly used patterns can be defined once and then easily used
in multiple recipes. in multiple recipes.
For reference information on the Yocto Project classes, see the
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" chapter of the
Yocto Project Reference Manual.
Class files end with the <filename>.bbclass</filename> filename extension. Class files end with the <filename>.bbclass</filename> filename extension.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various <listitem><para><emphasis>Configuration File:</emphasis>
<filename>.conf</filename> files provides global definitions of variables. Configuration information in various <filename>.conf</filename>
The <filename>conf/local.conf</filename> configuration file in the files provides global definitions of variables.
The <filename>conf/local.conf</filename> configuration file in
the
<link linkend='build-directory'>Build Directory</link> <link linkend='build-directory'>Build Directory</link>
contains user-defined variables that affect each build. contains user-defined variables that affect every build.
The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file The <filename>meta-yocto/conf/distro/poky.conf</filename>
defines Yocto "distro" configuration configuration file defines Yocto "distro" configuration
variables used only when building with this policy. variables used only when building with this policy.
Machine configuration files, which Machine configuration files, which
are located throughout the are located throughout the
<link linkend='source-directory'>Source Directory</link>, define <link linkend='source-directory'>Source Directory</link>, define
variables for specific hardware and are only used when building for that target variables for specific hardware and are only used when building
(e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines for that target (e.g. the
variables for the Texas Instruments ARM Cortex-A8 development board). <filename>machine/beagleboard.conf</filename> configuration
Configuration files end with a <filename>.conf</filename> filename extension. file defines variables for the Texas Instruments ARM Cortex-A8
development board).
Configuration files end with a <filename>.conf</filename>
filename extension.
</para></listitem> </para></listitem>
<listitem><para id='cross-development-toolchain'> <listitem><para id='cross-development-toolchain'>
<emphasis>Cross-Development Toolchain:</emphasis> <emphasis>Cross-Development Toolchain:</emphasis>
@ -611,10 +624,11 @@
<ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project
Application Developer's Guide</ulink>. Application Developer's Guide</ulink>.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Image:</emphasis> An image is the result produced when <listitem><para><emphasis>Image:</emphasis>
BitBake processes a given collection of recipes and related Metadata. An image is the result produced when BitBake processes a given
Images are the binary output that run on specific hardware or QEMU collection of recipes and related Metadata.
and for specific use cases. Images are the binary output that run on specific hardware or
QEMU and are used for specific use-cases.
For a list of the supported image types that the Yocto Project provides, see the For a list of the supported image types that the Yocto Project provides, see the
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
chapter in the Yocto Project Reference Manual.</para></listitem> chapter in the Yocto Project Reference Manual.</para></listitem>
@ -640,9 +654,12 @@
with OpenEmbedded (OE) that is shared between OE and the Yocto Project. with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
This Metadata is found in the <filename>meta</filename> directory of the This Metadata is found in the <filename>meta</filename> directory of the
<link linkend='source-directory'>Source Directory</link>.</para></listitem> <link linkend='source-directory'>Source Directory</link>.</para></listitem>
<listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project, <listitem><para><emphasis>Package:</emphasis>
this term refers to the packaged output from a baked recipe. In the context of the Yocto Project, this term refers a
A package is generally the compiled binaries produced from the recipe's sources. recipe's packaged output produced by BitBake (i.e. a
"baked recipe").
A package is generally the compiled binaries produced from the
recipe's sources.
You "bake" something by running it through BitBake.</para> You "bake" something by running it through BitBake.</para>
<para>It is worth noting that the term "package" can, in general, have subtle <para>It is worth noting that the term "package" can, in general, have subtle
meanings. For example, the packages referred to in the meanings. For example, the packages referred to in the
@ -673,24 +690,35 @@
by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded
build system becoming a build system for embedded images. build system becoming a build system for embedded images.
After Intel Corporation acquired OpenedHand, the project poky became the basis for After Intel Corporation acquired OpenedHand, the project poky became the basis for
the Yocto Project's build system. the Yocto Project's build system.</para>
<para>
Within the Yocto Project source repositories, <filename>poky</filename> Within the Yocto Project source repositories, <filename>poky</filename>
exists as a separate Git repository exists as a separate Git repository
that can be cloned to yield a local copy on the host system. that can be cloned to yield a local copy on the host system.
Thus, "poky" can refer to the local copy of the Source Directory used to develop within Thus, "poky" can refer to the local copy of the Source Directory used to develop within
the Yocto Project.</para></listitem> the Yocto Project.</para></listitem>
<listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages. <listitem><para><emphasis>Recipe:</emphasis>
A recipe describes where you get source code and which patches to apply. A set of instructions for building packages.
Recipes describe dependencies for libraries or for other recipes, and they A recipe describes where you get source code and which patches
also contain configuration and compilation options. to apply.
Recipes contain the logical unit of execution, the software/images to build, and Recipes describe dependencies for libraries or for other
use the <filename>.bb</filename> file extension.</para></listitem> recipes, and they also contain configuration and compilation
options.
Recipes contain the logical unit of execution, the software
to build, the images to build, and use the
<filename>.bb</filename> file extension.
</para></listitem>
<listitem> <listitem>
<para id='source-directory'><emphasis>Source Directory:</emphasis> <para id='source-directory'><emphasis>Source Directory:</emphasis>
This term refers to the directory structure created as a result This term refers to the directory structure created as a result
of creating a local copy of the <filename>poky</filename> Git of creating a local copy of the <filename>poky</filename> Git
repository <filename>git://git.yoctoproject.org/poky</filename> repository <filename>git://git.yoctoproject.org/poky</filename>
or expanding a released <filename>poky</filename> tarball. or expanding a released <filename>poky</filename> tarball.
<note>
Creating a local copy of the <filename>poky</filename>
Git repository is the recommended method for setting up
your Source Directory.
</note>
Sometimes you might hear the term "poky directory" used to refer Sometimes you might hear the term "poky directory" used to refer
to this directory structure. to this directory structure.
<note> <note>
@ -708,12 +736,12 @@
<para>When you create a local copy of the Git repository, you <para>When you create a local copy of the Git repository, you
can name the repository anything you like. can name the repository anything you like.
Throughout much of the documentation, <filename>poky</filename> Throughout much of the documentation, "poky"
is used as the name of the top-level folder of the local copy of is used as the name of the top-level folder of the local copy of
the poky Git repository. the poky Git repository.
So, for example, cloning the <filename>poky</filename> Git So, for example, cloning the <filename>poky</filename> Git
repository results in a local Git repository whose top-level repository results in a local Git repository whose top-level
folder is also named <filename>poky</filename>.</para> folder is also named "poky".</para>
<para>While it is not recommended that you use tarball expansion <para>While it is not recommended that you use tarball expansion
to setup the Source Directory, if you do, the top-level to setup the Source Directory, if you do, the top-level
@ -815,18 +843,23 @@
for a standard format for communicating the components, licenses, and copyrights for a standard format for communicating the components, licenses, and copyrights
associated with a software package. associated with a software package.
<ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source
Definition and the effort for reviewing and approving licenses that are OSD-conformant. Definition and the effort for reviewing and approving licenses that
conform to the Open Source Definition (OSD).
</para> </para>
<para> <para>
You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses You can find a list of the combined SPDX and OSI licenses that the
<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>. Yocto Project uses in the
<filename>meta/files/common-licenses</filename> directory in your
<link linkend='source-directory'>Source Directory</link>.
</para> </para>
<para> <para>
For information that can help you to maintain compliance with various open source licensing For information that can help you maintain compliance with various
during the lifecycle of a product created using the Yocto Project, see the open source licensing during the lifecycle of a product created using
"<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>" section. the Yocto Project, see the
"<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>"
section.
</para> </para>
</section> </section>
@ -889,12 +922,14 @@
</para> </para>
<para> <para>
It is important to understand that Git tracks content change and not files. It is important to understand that Git tracks content change and
not files.
Git uses "branches" to organize different development efforts. Git uses "branches" to organize different development efforts.
For example, the <filename>poky</filename> repository has For example, the <filename>poky</filename> repository has
<filename>denzil</filename>, <filename>danny</filename>, <filename>denzil</filename>, <filename>danny</filename>,
<filename>dylan</filename>, <filename>dora</filename>, <filename>dylan</filename>, <filename>dora</filename>,
and <filename>master</filename> branches among others. <filename>daisy</filename>, and <filename>master</filename> branches
among others.
You can see all the branches by going to You can see all the branches by going to
<ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
clicking on the clicking on the
@ -928,37 +963,38 @@
</literallayout> </literallayout>
In this example, the name of the top-level directory of your local In this example, the name of the top-level directory of your local
<link linkend='source-directory'>Source Directory</link> <link linkend='source-directory'>Source Directory</link>
is <filename>poky</filename>, is "poky" and the name of that local working area (local branch)
and the name of that local working area (local branch) you just you just created and checked out is "&DISTRO_NAME;".
created and checked out is <filename>&DISTRO_NAME;</filename>.
The files in your local repository now reflect the same files that The files in your local repository now reflect the same files that
are in the <filename>&DISTRO_NAME;</filename> development are in the "&DISTRO_NAME;" development branch of the
branch of the Yocto Project's <filename>poky</filename> Yocto Project's "poky" upstream repository.
upstream repository.
It is important to understand that when you create and checkout a It is important to understand that when you create and checkout a
local working branch based on a branch name, local working branch based on a branch name,
your local environment matches the "tip" of that development branch your local environment matches the "tip" of that development branch
at the time you created your local branch, which could be at the time you created your local branch, which could be
different from the files at the time of a similarly named release. different from the files at the time of a similarly named release.
In other words, creating and checking out a local branch based on the In other words, creating and checking out a local branch based on
<filename>&DISTRO_NAME;</filename> branch name is not the same as the "&DISTRO_NAME;" branch name is not the same as
cloning and checking out the <filename>master</filename> branch. cloning and checking out the "master" branch.
Keep reading to see how you create a local snapshot of a Yocto Project Release. Keep reading to see how you create a local snapshot of a Yocto
Project Release.
</para> </para>
<para> <para>
Git uses "tags" to mark specific changes in a repository. Git uses "tags" to mark specific changes in a repository.
Typically, a tag is used to mark a special point such as the final change Typically, a tag is used to mark a special point such as the final
before a project is released. change before a project is released.
You can see the tags used with the <filename>poky</filename> Git repository You can see the tags used with the <filename>poky</filename> Git
by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and repository by going to
<ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
clicking on the clicking on the
<filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename> <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
link beneath the "Tag" heading. link beneath the "Tag" heading.
</para> </para>
<para> <para>
Some key tags are <filename>bernard-5.0</filename>, <filename>denzil-7.0</filename>, Some key tags are <filename>dylan-9.0.0</filename>,
<filename>dora-10.0.0</filename>,
and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>. and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>.
These tags represent Yocto Project releases. These tags represent Yocto Project releases.
</para> </para>
@ -1007,7 +1043,7 @@
</para> </para>
<para> <para>
If you don’t know much about Git, you should educate If you do not know much about Git, you should educate
yourself by visiting the links previously mentioned. yourself by visiting the links previously mentioned.
</para> </para>
@ -1019,9 +1055,12 @@
<itemizedlist> <itemizedlist>
<listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository. <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository.
You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem> You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem>
<listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository. <listitem><para><emphasis><filename>git clone</filename>:</emphasis>
During collaboration, this command allows you to create a local repository that is on Creates a local clone of a Git repository.
equal footing with a fellow developer’s repository.</para></listitem> During collaboration, this command allows you to create a
local Git repository that is on equal footing with a fellow
developer’s Git repository.
</para></listitem>
<listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents <listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents
to the index that to the index that
Git uses to track changes. Git uses to track changes.
@ -1111,11 +1150,18 @@
</para> </para>
<para> <para>
The project also has contribution repositories known as "contrib" areas. The project also has an upstream contribution Git repository named
These areas temporarily hold changes to the project that have been submitted or committed <filename>poky-contrib</filename>.
by the Yocto Project development team and by community members that contribute to the project. You can see all the branches in this repository using the web interface
The maintainer determines if the changes are qualified to be moved from the "contrib" areas of the
into the "master" branch of the Git repository. <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
within the "Poky Support" area.
These branches temporarily hold changes to the project that have been
submitted or committed by the Yocto Project development team and by
community members who contribute to the project.
The maintainer determines if the changes are qualified to be moved
from the "contrib" branches into the "master" branch of the Git
repository.
</para> </para>
<para> <para>
@ -1143,11 +1189,13 @@
</para> </para>
<para> <para>
To summarize the environment: we have a single point of entry for changes into the project’s To summarize the environment: a single point of entry exists for
"master" branch of the Git repository, which is controlled by the project’s maintainer. changes into the project’s "master" branch of the Git repository,
And, we have a set of developers who independently develop, test, and submit changes which is controlled by the project’s maintainer.
to "contrib" areas for the maintainer to examine. And, a set of developers exist who independently develop, test, and
The maintainer then chooses which changes are going to become a permanent part of the project. submit changes to "contrib" areas for the maintainer to examine.
The maintainer then chooses which changes are going to become a
permanent part of the project.
</para> </para>
<para> <para>
@ -1430,19 +1478,20 @@
you used. It may also be helpful if you mention how you tested the change. you used. It may 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. Provide as much detail as you can in the body of the commit message.
</para></listitem> </para></listitem>
<listitem><para>If the change addresses a specific bug or issue that is <listitem><para>
associated with a bug-tracking ID, include a reference to that ID in If the change addresses a specific bug or issue that is
your detailed description. associated with a bug-tracking ID, include a reference to that
For example, the Yocto Project uses a specific convention for bug ID in your detailed description.
references - any commit that addresses a specific bug should include the For example, the Yocto Project uses a specific convention for
bug ID in the description (typically at the beginning) as follows: bug references - any commit that addresses a specific bug should
use the following form for the detailed description:
<literallayout class='monospaced'> <literallayout class='monospaced'>
[YOCTO #&lt;bug-id&gt;] Fixes [YOCTO #&lt;bug-id&gt;]
&lt;detailed description of change&gt; &lt;detailed description of change&gt;
</literallayout></para></listitem> </literallayout></para></listitem>
Where &lt;bug-id&gt; is replaced with the specific bug ID from the Where &lt;bug-id&gt; is replaced with the specific bug ID from
Yocto Project Bugzilla instance. the Yocto Project Bugzilla instance.
</itemizedlist> </itemizedlist>
</para> </para>
@ -1466,10 +1515,16 @@
<listitem><para>Make your changes in your local Git repository.</para></listitem> <listitem><para>Make your changes in your local Git repository.</para></listitem>
<listitem><para>Stage your changes by using the <filename>git add</filename> <listitem><para>Stage your changes by using the <filename>git add</filename>
command on each file you changed.</para></listitem> command on each file you changed.</para></listitem>
<listitem><para>Commit the change by using the <filename>git commit</filename> <listitem><para>
command and push it to the "contrib" repository. Commit the change by using the
Be sure to provide a commit message that follows the project’s commit message standards <filename>git commit</filename> command.
as described earlier.</para></listitem> 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 <listitem><para>Notify the maintainer that you have pushed a change by making a pull
request. request.
The Yocto Project provides two scripts that conveniently let you generate and send The Yocto Project provides two scripts that conveniently let you generate and send