[gnome-continuous-yocto/gnomeostree-3.28-rocko: 6702/8267] dev-manual: Clarifications for files in checkout out by tag

[Emmanuele Bassi <ebassi src gnome org>]

commit b9430113c6455c858df5e3b5ee08837bc833243f
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Wed Jun 28 16:24:29 2017 -0700

    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>

 documentation/dev-manual/dev-manual-start.xml |   17 ++++++++++++-----
 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 364a763..0e48043 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>