documentation/dev-manual: Edits to clarify YP files

These edits help explain the differences between local YP files
created through a tarball extraction vs cloning a Git repository.

(From yocto-docs rev: ed368800c3e9ece71d27d6d690f0ddc264a4c2da)

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

2 files changed, 18 insertions, 4 deletions

diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 95ef877..2ff66a4 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -205,8 +205,8 @@
             by the maintainer of the source code.
             For example, in order for a developer to work on a particular piece of code, they need to 
             first get a copy of it from an "upstream" source.</para></listitem>
-        <listitem><para><emphasis>Yocto Project Files:</emphasis>
-            This term refers to the directory structure created as a result of downloading 
+        <listitem><para id='yocto-project-files'><emphasis>Yocto Project Files:</emphasis>
+            This term refers to the directory structure created as a result of either downloading 
             and unpacking a Yocto Project release tarball or setting up a Git repository
             by cloning <filename>git://git.yoctoproject.org/poky</filename>.
             Sometimes the term "the Yocto Project Files structure" is used as well.</para>
@@ -220,6 +220,16 @@
             results in a Yocto Project file structure whose Yocto Project source directory is named 
             <filename>poky-edison-6.0</filename>.
             If you create a Git repository, then you can name the repository anything you like.</para>
+            <para>It is important to understand the differences between Yocto Project Files created
+            by unpacking a release tarball as compared to cloning 
+            <filename>git://git.yoctoproject.org/poky</filename>.
+            When you unpack a tarball, you have an exact copy of the files based on the time of 
+            release - a fixed release point.
+            Any changes you make to your local Yocto Project files are on top of the release.
+            On the otherhand, when you clone the Yocto Project Git repository, you have an
+            active development repository.
+            In this case, any local changes you make to the Yocto Project can be later applied to active
+            development branches of the upstream Yocto Project Git repository.</para>
             <para>You can find instruction on how to set up the Yocto Project files on your 
             host development system by reading 
             the 
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 6d68a08..3cb6750 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -63,7 +63,9 @@
                 for the supported distributions.</para></listitem>
             <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>  
                 You need a release of the Yocto Project.  
-                You can get set up with local Yocto Project files one of two ways depending on whether you 
+                You can get set up with local 
+                <link linkend='yocto-project-files'>Yocto Project Files</link> one of two ways 
+                depending on whether you 
                 are going to be contributing back into the Yocto Project source repository or not.
                 <note>
                     Regardless of the method you use, this manual refers to the resulting 
@@ -89,7 +91,9 @@
                         back into the Yocto Project, you should use Git commands to set up a local 
                         Git repository of the Yocto Project files.  
                         Doing so creates a Git repository with a complete history of changes and allows 
-                        you to easily submit your changes upstream to the project.</para>
+                        you to easily submit your changes upstream to the project.
+                        Because you cloned the repository, you have access to all the Yocto Project development
+                        branches and tag names used in the upstream repository.</para>
                        <para>The following transcript shows how to clone the Yocto Project files'  
                        Git repository into the current working directory.  
                        The command creates the repository in a directory named <filename>poky</filename>.