dev-manual: Clarifications for files in checkout out by tag

I put in some edits to be very clear on the state of the files
for the user when they check out by tag.

(From yocto-docs rev: 622d324e7f167f55a5de86ec7af65d7554f2aec8)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 12 insertions, 5 deletions

diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index 364a7631f2..0e48043d38 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -686,13 +686,19 @@
         <title>Checking Out by Tag in Poky</title>
 
         <para>
-            Similar to branches, the upstream repository has tags used
-            to mark significant commits such as a completed release or
-            stage of a release.
+            Similar to branches, the upstream repository uses tags
+            to mark specific commits associated with significant points in
+            a development branch (i.e. a release point or stage of a
+            release).
             You might want to set up a local branch based on one of those
             points in the repository.
             The process is similar to checking out by branch name except you
             use tag names.
+            <note>
+                Checking out a branch based on a tag names gives you a
+                stable set of files not affected by development on the
+                branch above the tag.
+            </note>
             <orderedlist>
                 <listitem><para>
                     <emphasis>Switch to the Poky Directory:</emphasis>
@@ -743,8 +749,9 @@
                     branch named "my_yocto_2.2_M2", which is based on
                     the commit in the upstream poky repository that has
                     the same tag.
-                    The files you have available locally when you are
-                    checked out to that branch are a snapshot of the
+                    In this example, the files you have available locally
+                    as a result of the <filename>checkout</filename>
+                    command are a snapshot of the
                     "morty" development branch at the point where
                     milestone two was reached.
                     </para></listitem>