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>

1 files changed, 159 insertions, 104 deletions

diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index eab563f3d0..77c14a6611 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -171,7 +171,7 @@
                         pool similarly to how the developer workstations
                         contribute.
                         For information, see the
-                        <link linkend='best-practices-autobuilders'>Autobuilders</link>
+                        "<link linkend='best-practices-autobuilders'>Autobuilders</link>"
                         section.</para></listitem>
                     <listitem><para>Build stand-alone tarballs that contain
                         "missing" system requirements if for some reason
@@ -184,8 +184,8 @@
                         on most distributions.</para></listitem>
                     <listitem><para>Use a small number of shared,
                         high performance systems for testing purposes
-                        (e.g. dual six core Xeons with 24GB RAM and plenty of
-                        disk space).
+                        (e.g. dual, six-core Xeons with 24 Gbytes of RAM
+                        and plenty of disk space).
                         Developers can use these systems for wider, more
                         extensive testing while they continue to develop
                         locally using their primary development system.
@@ -222,10 +222,8 @@
             allows you to work remotely, and then connects back to the
             infrastructure.
             <note>
-                For information about BitBake and SCMs, see the
-                BitBake manual located in the
-                <filename>bitbake/doc/manual</filename> directory of the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                For information about BitBake, see the
+                <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
             </note>
         </para>
 
@@ -238,7 +236,7 @@
             being used to generate the web interface that lets you view the
             repositories.
             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
             or as much as necessary.
         </para>
@@ -298,8 +296,8 @@
                 <listitem><para>Allows triggering of automated image booting
                     and testing under the QuickEMUlator (QEMU).
                     </para></listitem>
-                <listitem><para>Supports incremental build testing and from
-                    scratch builds.</para></listitem>
+                <listitem><para>Supports incremental build testing and
+                    from-scratch builds.</para></listitem>
                 <listitem><para>Shares output that allows developer
                     testing and historical regression investigation.
                     </para></listitem>
@@ -365,14 +363,18 @@
                     See the "<link linkend='understanding-and-creating-layers'>Understanding
                     and Creating Layers</link>" section for more information on
                     layers.</para></listitem>
-                <listitem><para>Separate the project's Metadata and code by using
+                <listitem><para>
+                    Separate the project's Metadata and code by using
                     separate Git repositories.
-                    See the "<link linkend='yocto-project-repositories'>Yocto Project
-                    Source Repositories</link>" section for information on these
-                    repositories.
-                    See the "<link linkend='getting-setup'>Getting Set Up</link>" section
-                    for information on how to set up various Yocto Project related
-                    Git repositories.</para></listitem>
+                    See the
+                    "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>"
+                    section for information on these repositories.
+                    See the
+                    "<link linkend='getting-setup'>Getting Set Up</link>"
+                    section for information on how to set up local Git
+                    repositories for related upstream Yocto Project
+                    Git repositories.
+                    </para></listitem>
                 <listitem><para>Set up the directory for the shared state cache
                     (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
                     where it makes sense.
@@ -389,7 +391,7 @@
                     See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
                     section.</para></listitem>
                 <listitem><para>Send changes to the core sooner than later
-                    as others 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
                     "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
                     section.
@@ -415,7 +417,9 @@
         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
         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
         the Yocto Project's tools, Board Support Packages, and so forth.
     </para>
@@ -447,9 +451,9 @@
                 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
                 </para></listitem>
             <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>
-                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.
                 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>
@@ -494,11 +498,11 @@
                 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section.
                 </para></listitem>
             <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
-                The task executor and scheduler used by
-                the OpenEmbedded build system to build images.
-                For more information on BitBake, see the BitBake documentation
-                in the <filename>bitbake/doc/manual</filename> directory of the
-                <link linkend='source-directory'>Source Directory</link>.</para></listitem>
+                The task executor and scheduler used by the OpenEmbedded build
+                system to build images.
+                For more information on BitBake, see the
+                <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+                </para></listitem>
             <listitem>
                 <para id='build-directory'><emphasis>Build Directory:</emphasis>
                 This term refers to the area used by the OpenEmbedded build system for builds.
@@ -533,8 +537,9 @@
      $ cd $HOME
      $ source poky/&OE_INIT_FILE; test-builds
                             </literallayout></para></listitem>
-                        <listitem><para>Provide a directory path and
-                            specifically name the build directory.
+                        <listitem><para>
+                            Provide a directory path and
+                            specifically name the Build Directory.
                             Any intermediate folders in the pathname must
                             exist.
                             This next example creates a Build Directory named
@@ -557,23 +562,31 @@
             <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
                 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.
                 </para></listitem>
-            <listitem><para><emphasis>Configuration File:</emphasis>  Configuration information in various
-                <filename>.conf</filename> files provides global definitions of variables.
-                The <filename>conf/local.conf</filename> configuration file in the
+            <listitem><para><emphasis>Configuration File:</emphasis>
+                Configuration information in various <filename>.conf</filename>
+                files provides global definitions of variables.
+                The <filename>conf/local.conf</filename> configuration file in
+                the
                 <link linkend='build-directory'>Build Directory</link>
-                contains user-defined variables that affect each build.
-                The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file
-                defines Yocto "distro" configuration
+                contains user-defined variables that affect every build.
+                The <filename>meta-yocto/conf/distro/poky.conf</filename>
+                configuration file defines Yocto "distro" configuration
                 variables used only when building with this policy.
                 Machine configuration files, which
                 are located throughout the
                 <link linkend='source-directory'>Source Directory</link>, define
-                variables for specific hardware and are only used when building for that target
-                (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines
-                variables for the Texas Instruments ARM Cortex-A8 development board).
-                Configuration files end with a <filename>.conf</filename> filename extension.
+                variables for specific hardware and are only used when building
+                for that target (e.g. the
+                <filename>machine/beagleboard.conf</filename> configuration
+                file defines variables for the Texas Instruments ARM Cortex-A8
+                development board).
+                Configuration files end with a <filename>.conf</filename>
+                filename extension.
                 </para></listitem>
             <listitem><para id='cross-development-toolchain'>
                 <emphasis>Cross-Development Toolchain:</emphasis>
@@ -611,10 +624,11 @@
                     <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project
                     Application Developer's Guide</ulink>.
                 </para></listitem>
-            <listitem><para><emphasis>Image:</emphasis> An image is the result produced when
-                BitBake processes a given collection of recipes and related Metadata.
-                Images are the binary output that run on specific hardware or QEMU
-                and for specific use cases.
+            <listitem><para><emphasis>Image:</emphasis>
+                An image is the result produced when BitBake processes a given
+                collection of recipes and related Metadata.
+                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
                 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
                 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.
                 This Metadata is found in the <filename>meta</filename> directory of the
                 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
-            <listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project,
-                this term refers to the packaged output from a baked recipe.
-                A package is generally the compiled binaries produced from the recipe's sources.
+            <listitem><para><emphasis>Package:</emphasis>
+                In the context of the Yocto Project, this term refers a
+                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>
                 <para>It is worth noting that the term "package" can, in general, have subtle
                 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
                 build system becoming a build system for embedded images.
                 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>
                 exists as a separate Git repository
                 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
                 the Yocto Project.</para></listitem>
-            <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages.
-                A recipe describes where you get source code and which patches to apply.
-                Recipes describe dependencies for libraries or for other recipes, and they
-                also contain configuration and compilation options.
-                Recipes contain the logical unit of execution, the software/images to build, and
-                use the <filename>.bb</filename> file extension.</para></listitem>
+            <listitem><para><emphasis>Recipe:</emphasis>
+                A set of instructions for building packages.
+                A recipe describes where you get source code and which patches
+                to apply.
+                Recipes describe dependencies for libraries or for other
+                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>
                 <para id='source-directory'><emphasis>Source Directory:</emphasis>
                 This term refers to the directory structure created as a result
                 of creating a local copy of the <filename>poky</filename> Git
                 repository <filename>git://git.yoctoproject.org/poky</filename>
                 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
                 to this directory structure.
                 <note>
@@ -708,12 +736,12 @@
 
                 <para>When you create a local copy of the Git repository, you
                 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
                 the poky Git repository.
                 So, for example, cloning the <filename>poky</filename> Git
                 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
                 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
         associated with a software package.
         <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>
-        You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses
-        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>.
+        You can find a list of the combined SPDX and OSI licenses that the
+        Yocto Project uses in the
+        <filename>meta/files/common-licenses</filename> directory in your
+        <link linkend='source-directory'>Source Directory</link>.
     </para>
 
     <para>
-        For information that can help you to maintain compliance with various open source licensing
-        during the lifecycle of a product created using 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.
+        For information that can help you maintain compliance with various
+        open source licensing during the lifecycle of a product created using
+        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>
 </section>
 
@@ -889,12 +922,14 @@
         </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.
             For example, the <filename>poky</filename> repository has
             <filename>denzil</filename>, <filename>danny</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
             <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
             clicking on the
@@ -928,37 +963,38 @@
             </literallayout>
             In this example, the name of the top-level directory of your local
             <link linkend='source-directory'>Source Directory</link>
-            is <filename>poky</filename>,
-            and the name of that local working area (local branch) you just
-            created and checked out is <filename>&DISTRO_NAME;</filename>.
+            is "poky" and the name of that local working area (local branch)
+            you just created and checked out is "&DISTRO_NAME;".
             The files in your local repository now reflect the same files that
-            are in the <filename>&DISTRO_NAME;</filename> development
-            branch of the Yocto Project's <filename>poky</filename>
-            upstream repository.
+            are in the "&DISTRO_NAME;" development branch of the
+            Yocto Project's "poky" upstream repository.
             It is important to understand that when you create and checkout a
             local working branch based on a branch name,
             your local environment matches the "tip" of that development branch
             at the time you created your local branch, which could be
             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
-            <filename>&DISTRO_NAME;</filename> branch name is not the same as
-            cloning and checking out the <filename>master</filename> branch.
-            Keep reading to see how you create a local snapshot of a Yocto Project Release.
+            In other words, creating and checking out a local branch based on
+            the "&DISTRO_NAME;" branch name is not the same as
+            cloning and checking out the "master" branch.
+            Keep reading to see how you create a local snapshot of a Yocto
+            Project Release.
         </para>
 
         <para>
             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
-            before a project is released.
-            You can see the tags used with the <filename>poky</filename> Git repository
-            by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
+            Typically, a tag is used to mark a special point such as the final
+            change before a project is released.
+            You can see the tags used with the <filename>poky</filename> Git
+            repository by going to
+            <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
             clicking on the
             <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
             link beneath the "Tag" heading.
         </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>.
             These tags represent Yocto Project releases.
         </para>
@@ -1007,7 +1043,7 @@
         </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.
         </para>
 
@@ -1019,9 +1055,12 @@
             <itemizedlist>
                 <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>
-                <listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository.
-                    During collaboration, this command allows you to create a local repository that is on
-                    equal footing with a fellow developer’s repository.</para></listitem>
+                <listitem><para><emphasis><filename>git clone</filename>:</emphasis>
+                    Creates a local clone of a Git repository.
+                    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
                     to the index that
                     Git uses to track changes.
@@ -1111,11 +1150,18 @@
     </para>
 
     <para>
-        The project also has contribution repositories known as "contrib" areas.
-        These areas temporarily hold changes to the project that have been submitted or committed
-        by the Yocto Project development team and by community members that contribute to the project.
-        The maintainer determines if the changes are qualified to be moved from the "contrib" areas
-        into the "master" branch of the Git repository.
+        The project also has an upstream contribution Git repository named
+        <filename>poky-contrib</filename>.
+        You can see all the branches in this repository using the web interface
+        of the
+        <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>
@@ -1143,11 +1189,13 @@
     </para>
 
     <para>
-        To summarize the environment:  we have a single point of entry for changes into the project’s
-        "master" branch of the Git repository, which is controlled by the project’s maintainer.
-        And, we have a set of developers who independently develop, test, and 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.
+        To summarize the environment:  a single point of entry exists for
+        changes into the project’s "master" branch of the Git repository,
+        which is controlled by the project’s maintainer.
+        And, a set of developers exist who independently develop, test, and
+        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>
@@ -1430,19 +1478,20 @@
                 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.
                 </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 include the
-                bug ID in the description (typically at the beginning) as follows:
+            <listitem><para>
+                If the change addresses a specific bug or issue that is
+                associated with a bug-tracking ID, include a reference to that
+                ID in your detailed description.
+                For example, the Yocto Project uses a specific convention for
+                bug references - any commit that addresses a specific bug should
+                use the following form for the detailed description:
                 <literallayout class='monospaced'>
-     [YOCTO #&lt;bug-id&gt;]
+     Fixes [YOCTO #&lt;bug-id&gt;]
 
      &lt;detailed description of change&gt;
                 </literallayout></para></listitem>
-                Where &lt;bug-id&gt; is replaced with the specific bug ID from the
-                Yocto Project Bugzilla instance.
+                Where &lt;bug-id&gt; is replaced with the specific bug ID from
+                the Yocto Project Bugzilla instance.
         </itemizedlist>
     </para>
 
@@ -1466,10 +1515,16 @@
                 <listitem><para>Make your changes in your local Git repository.</para></listitem>
                 <listitem><para>Stage your changes by using the <filename>git add</filename>
                     command on each file you changed.</para></listitem>
-                <listitem><para>Commit the change by using the <filename>git commit</filename>
-                    command and push it to the "contrib" repository.
-                    Be sure to provide a commit message that follows the project’s commit message standards
-                    as described earlier.</para></listitem>
+                <listitem><para>
+                    Commit the change by using the
+                    <filename>git commit</filename> command.
+                    Be sure to provide a commit message that follows the
+                    project’s commit message standards as described earlier.
+                    </para></listitem>
+                <listitem><para>
+                    Push the change to the upstream "contrib" repository by
+                    using the <filename>git push</filename> command.
+                    </para></listitem>
                 <listitem><para>Notify the maintainer that you have pushed a change by making a pull
                     request.
                     The Yocto Project provides two scripts that conveniently let you generate and send