documentation/dev-manual: Re-org of topics

Several topics in the "Common Tasks" chapter really fit better in
the "Newbie" chapter.  I moved these sections out.  I also combined
information from the section on submitting changes from the
"Common Tasks" and the "Newbie" chapter to live in the "Newbie"
chapter only.

(From yocto-docs rev: 90fa8c125e545c57a5a994dd59715b73c5c4882f)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 155 insertions, 213 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index cedab513bb..9f7d04244a 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1774,6 +1774,91 @@ so that there are some definite steps on how to do this.  I need more detail her
         </section>
     </section>
 
+    <section id="usingpoky-changes-updatingimages">
+        <title>Updating Existing Images</title>
+
+        <para>
+            Often, rather than re-flashing a new image, you might wish to install updated 
+            packages into an existing running system. 
+            You can do this by first sharing the <filename>tmp/deploy/ipk/</filename> directory
+            through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename> 
+            to point at the shared server.
+            Following is an example:
+            <literallayout class='monospaced'>
+     $ src/gz all http://www.mysite.com/somedir/deploy/ipk/all
+     $ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
+     $ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
+            </literallayout>
+        </para>
+    </section>
+
+    <section id="usingpoky-changes-prbump">
+        <title>Incrementing a Package Revision Number</title>
+
+        <para>
+            If a committed change results in changing the package output,
+            then the value of the 
+            <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PR'>PR</ulink></filename> 
+            variable needs to be increased 
+            (or "bumped") as part of that commit. 
+            This means that for new recipes you must be sure to add the <filename>PR</filename>
+            variable and set its initial value equal to "r0".  
+            Failing to define <filename>PR</filename> makes it easy to miss when you bump a package.
+            Note that you can only use integer values following the "r" in the 
+            <filename>PR</filename> variable.
+        </para>
+
+        <para>
+            If you are sharing a common <filename>.inc</filename> file with multiple recipes, 
+            you can also use the 
+            <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-INC_PR'>INC_PR</ulink></filename> 
+            variable to ensure that 
+            the recipes sharing the <filename>.inc</filename> file are rebuilt when the 
+            <filename>.inc</filename> file itself is changed. 
+            The <filename>.inc</filename> file must set <filename>INC_PR</filename>
+            (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
+            to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
+            If the <filename>.inc</filename> file is changed then its 
+            <filename>INC_PR</filename> should be incremented.
+        </para>
+
+        <para> 
+            When upgrading the version of a package, assuming the 
+            <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PV'>PV</ulink></filename> 
+            changes, the <filename>PR</filename> variable should be reset to "r0"
+            (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
+        </para>
+
+        <para>
+            Usually, version increases occur only to packages.
+            However, if for some reason <filename>PV</filename> changes but does not 
+            increase, you can increase the 
+            <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PE'>PE</ulink></filename> 
+            variable (Package Epoch).
+            The <filename>PE</filename> variable defaults to "0".
+        </para>
+
+        <para>
+            Version numbering strives to follow the 
+            <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
+            Debian Version Field Policy Guidelines</ulink>.
+            These guidelines define how versions are compared and what "increasing" a version means.
+        </para>
+
+        <para>
+            There are two reasons for following the previously mentioned guidelines.
+            First, to ensure that when a developer updates and rebuilds, they get all the changes to
+            the repository and do not have to remember to rebuild any sections.
+            Second, to ensure that target users are able to upgrade their
+            devices using package manager commands such as <filename>opkg upgrade</filename> 
+            (or similar commands for dpkg/apt or rpm-based systems). 
+        </para>
+
+        <para>
+            The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
+        </para>
+    </section>
+
     <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
         <title>Handling a Package Name Alias</title>
         <para>
@@ -1870,218 +1955,6 @@ so that there are some definite steps on how to do this.  I need more detail her
             build directory that is different than the source directory.
         </para>
     </section>
-
-    <section id="usingpoky-changes">
-        <title>Making and Maintaining Changes</title>
-        <para>
-            Because the Yocto Project is extremely configurable and flexible, 
-            we recognize that developers will want 
-            to extend, configure or optimize it for their specific uses.
-            To best keep pace with future Yocto Project changes,
-            we recommend you make controlled changes to the Yocto Project.
-        </para>
-
-        <para>
-            The Yocto Project supports a "<link linkend='understanding-and-creating-layers'>layers</link>" concept.
-            If you use layers properly, you can ease future upgrades and allow segregation
-            between the Yocto Project core and a given developer's changes. 
-            The following section provides more advice on managing changes to the Yocto Project.
-        </para>
-
-        <section id="usingpoky-changes-commits">
-            <title>Committing Changes</title>
-
-            <para>
-                Modifications to the Yocto Project are often managed under some kind of source
-                revision control system. 
-                Because some simple practices can significantly improve usability, policy for committing changes
-                is important.
-                It helps to use a consistent documentation style when committing changes. 
-                The Yocto Project development team has found the following practices work well: 
-                <itemizedlist>
-                    <listitem><para>The first line of the commit summarizes the change and begins with the 
-                        name of the affected package or packages.
-                        However, not all changes apply to specific packages. 
-                        Consequently, the prefix could also be a machine name or class name.</para></listitem>
-                    <listitem><para>The second part of the commit (if needed) is a longer more detailed 
-                        description of the changes.  
-                        Placing a blank line between the first and second parts helps with 
-                        readability.</para></listitem>
-                </itemizedlist>
-            </para>
-
-            <para>
-                Following is an example commit:
-                <literallayout class='monospaced'>
-    bitbake/data.py: Add emit_func() and generate_dependencies() functions
-    
-    These functions allow generation of dependency data between functions and
-    variables allowing moves to be made towards generating checksums and allowing
-    use of the dependency information in other parts of BitBake.
-    
-    Signed-off-by: Richard Purdie richard.purdie@linuxfoundation.org
-                </literallayout>
-            </para>
-
-            <para>
-                All commits should be self-contained such that they leave the 
-                metadata in a consistent state that builds both before and after the 
-                commit is made. 
-                Besides being a good practice to follow, it helps ensure autobuilder test results
-                are valid.
-            </para>
-        </section>
-
-        <section id="usingpoky-changes-prbump">
-            <title>Package Revision Incrementing</title>
-
-            <para>
-                If a committed change results in changing the package output,
-                then the value of the 
-                <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PR'>PR</ulink></filename> 
-                variable needs to be increased 
-                (or "bumped") as part of that commit. 
-                This means that for new recipes you must be sure to add the <filename>PR</filename>
-                variable and set its initial value equal to "r0".  
-                Failing to define <filename>PR</filename> makes it easy to miss when you bump a package.
-                Note that you can only use integer values following the "r" in the 
-                <filename>PR</filename> variable.
-            </para>
-
-            <para>
-                If you are sharing a common <filename>.inc</filename> file with multiple recipes, 
-                you can also use the 
-                <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-INC_PR'>INC_PR</ulink></filename> 
-                variable to ensure that 
-                the recipes sharing the <filename>.inc</filename> file are rebuilt when the 
-                <filename>.inc</filename> file itself is changed. 
-                The <filename>.inc</filename> file must set <filename>INC_PR</filename>
-                (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
-                to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
-                If the <filename>.inc</filename> file is changed then its 
-                <filename>INC_PR</filename> should be incremented.
-            </para>
-
-            <para> 
-                When upgrading the version of a package, assuming the 
-                <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PV'>PV</ulink></filename> 
-                changes, the <filename>PR</filename> variable should be reset to "r0"
-                (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
-            </para>
-
-            <para>
-                Usually, version increases occur only to packages.
-                However, if for some reason <filename>PV</filename> changes but does not 
-                increase, you can increase the 
-                <filename><ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#var-PE'>PE</ulink></filename> 
-                variable (Package Epoch).
-                The <filename>PE</filename> variable defaults to "0".
-            </para>
-
-            <para>
-                Version numbering strives to follow the 
-                <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
-                Debian Version Field Policy Guidelines</ulink>.
-                These guidelines define how versions are compared and what "increasing" a version means.
-            </para>
-
-            <para>
-                There are two reasons for following the previously mentioned guidelines.
-                First, to ensure that when a developer updates and rebuilds, they get all the changes to
-                the repository and do not have to remember to rebuild any sections.
-                Second, to ensure that target users are able to upgrade their
-                devices using package manager commands such as <filename>opkg upgrade</filename> 
-                (or similar commands for dpkg/apt or rpm-based systems). 
-            </para>
-
-            <para>
-                The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
-            </para>
-        </section>
-
-        <section id="usingpoky-changes-collaborate">
-            <title>Using The Yocto Project in a Team Environment</title>
-
-            <para>
-                It might not be immediately clear how you can use the Yocto Project in a team environment, 
-                or scale it for a large team of developers. 
-                The specifics of any situation determine the best solution.
-                Granted that the Yocto Project offers immense flexibility regarding this, practices do exist 
-                that experience has shown work well.
-            </para>
-
-            <para>
-                The core component of any development effort with the Yocto Project is often an 
-                automated build and testing framework along with an image generation process. 
-                You can use these core components to check that the metadata can be built, 
-                highlight when commits break the build, and provide up-to-date images that 
-                allow developers to test the end result and use it as a base platform for further 
-                development. 
-                Experience shows that buildbot is a good fit for this role. 
-                What works well is to configure buildbot to make two types of builds:
-                incremental and full (from scratch).  
-                See <ulink url='http://autobuilder.yoctoproject.org:8010/'>the buildbot for the 
-                Yocto Project</ulink> for an example implementation that uses buildbot.
-            </para>
-
-            <para>
-                You can tie incremental builds to a commit hook that triggers the build
-                each time a commit is made to the metadata.  
-                This practice results in useful acid tests that determine whether a given commit 
-                breaks the build in some serious way. 
-                Associating a build to a commit can catch a lot of simple errors.
-                Furthermore, the tests are fast so developers can get quick feedback on changes.
-            </para>
-
-            <para>
-                Full builds build and test everything from the ground up. 
-                These types of builds usually happen at predetermined times like during the 
-                night when the machine load is low.
-            </para>
-
-            <para>
-                Most teams have many pieces of software undergoing active development at any given time. 
-                You can derive large benefits by putting these pieces under the control of a source 
-                control system that is compatible with the Yocto Project (i.e. Git or Subversion (SVN).
-                You can then set the autobuilder to pull the latest revisions of the packages 
-                and test the latest commits by the builds.
-                This practice quickly highlights issues. 
-                The Yocto Project easily supports testing configurations that use both a 
-                stable known good revision and a floating revision.
-                The Yocto Project can also take just the changes from specific source control branches.
-                This capability allows you to track and test specific changes.
-            </para>
-
-            <para>
-                Perhaps the hardest part of setting this up is defining the software project or 
-                the Yocto Project metadata policies that surround the different source control systems.
-                Of course circumstances will be different in each case.
-                However, this situation reveals one of the Yocto Project's advantages - 
-                the system itself does not
-                force any particular policy on users, unlike a lot of build systems. 
-                The system allows the best policies to be chosen for the given circumstances.
-            </para>
-        </section>
-
-        <section id="usingpoky-changes-updatingimages">
-            <title>Updating Existing Images</title>
-
-            <para>
-                Often, rather than re-flashing a new image, you might wish to install updated 
-                packages into an existing running system. 
-                You can do this by first sharing the <filename>tmp/deploy/ipk/</filename> directory
-                through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename> 
-                to point at the shared server.
-                Following is an example:
-                <literallayout class='monospaced'>
-     $ src/gz all http://www.mysite.com/somedir/deploy/ipk/all
-     $ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
-     $ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
-                </literallayout>
-            </para>
-        </section>
-    </section>
-
 </chapter>
 
 <!-- 
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 1b5ef07398..9234a7175a 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -53,6 +53,70 @@
     </para>
 </section>
 
+<section id="usingpoky-changes-collaborate">
+    <title>Using The Yocto Project in a Team Environment</title>
+
+    <para>
+        It might not be immediately clear how you can use the Yocto Project in a team environment, 
+        or scale it for a large team of developers. 
+        The specifics of any situation determine the best solution.
+        Granted that the Yocto Project offers immense flexibility regarding this, practices do exist 
+        that experience has shown work well.
+    </para>
+
+    <para>
+        The core component of any development effort with the Yocto Project is often an 
+        automated build and testing framework along with an image generation process. 
+        You can use these core components to check that the metadata can be built, 
+        highlight when commits break the build, and provide up-to-date images that 
+        allow developers to test the end result and use it as a base platform for further 
+        development. 
+        Experience shows that buildbot is a good fit for this role. 
+        What works well is to configure buildbot to make two types of builds:
+        incremental and full (from scratch).  
+        See <ulink url='http://autobuilder.yoctoproject.org:8010/'>the buildbot for the 
+        Yocto Project</ulink> for an example implementation that uses buildbot.
+    </para>
+
+    <para>
+        You can tie incremental builds to a commit hook that triggers the build
+        each time a commit is made to the metadata.  
+        This practice results in useful acid tests that determine whether a given commit 
+        breaks the build in some serious way. 
+        Associating a build to a commit can catch a lot of simple errors.
+        Furthermore, the tests are fast so developers can get quick feedback on changes.
+    </para>
+
+    <para>
+        Full builds build and test everything from the ground up. 
+        These types of builds usually happen at predetermined times like during the 
+        night when the machine load is low.
+    </para>
+
+    <para>
+        Most teams have many pieces of software undergoing active development at any given time. 
+        You can derive large benefits by putting these pieces under the control of a source 
+        control system that is compatible with the Yocto Project (i.e. Git or Subversion (SVN).
+        You can then set the autobuilder to pull the latest revisions of the packages 
+        and test the latest commits by the builds.
+        This practice quickly highlights issues. 
+        The Yocto Project easily supports testing configurations that use both a 
+        stable known good revision and a floating revision.
+        The Yocto Project can also take just the changes from specific source control branches.
+        This capability allows you to track and test specific changes.
+    </para>
+
+    <para>
+        Perhaps the hardest part of setting this up is defining the software project or 
+        the Yocto Project metadata policies that surround the different source control systems.
+        Of course circumstances will be different in each case.
+        However, this situation reveals one of the Yocto Project's advantages - 
+        the system itself does not
+        force any particular policy on users, unlike a lot of build systems. 
+        The system allows the best policies to be chosen for the given circumstances.
+    </para>
+</section>
+
 <section id='yocto-project-repositories'>
     <title>Yocto Project Source Repositories</title>
 
@@ -797,6 +861,8 @@
 
     <para>
         Contributions to the Yocto Project are very welcome. 
+        Because the Yocto Project is extremely configurable and flexible, we recognize that developers 
+        will want to extend, configure or optimize it for their specific uses.
         You should send patches to the appropriate Yocto Project mailing list to get them 
         in front of the Yocto Project Maintainer.
         For a list of the Yocto Project mailing lists, see the
@@ -866,7 +932,10 @@
     <para>
         In a collaborative environment, it is necessary to have some sort of standard 
         or method through which you submit changes.  
-        Otherwise, things could get quite chaotic.  
+        Otherwise, things could get quite chaotic.
+        One general practice to follow is to make small, controlled changes to the 
+        Yocto Project.
+        Keeping changes small and isolated lets you best keep pace with future Yocto Project changes.
     </para>
 
     <para>