[svnbook commit] r1527 - in trunk/src/en: . book

[cmpilato]

Author: cmpilato
Date: Thu Jul  7 03:54:55 2005
New Revision: 1527

Modified:
   trunk/src/en/TODO
   trunk/src/en/book/ch07.xml
Log:
* src/en/book/ch07.xml
  (Externals Definitions): Add tip about using explicit revision numbers.

* src/en/TODO
  Note the completion of the related TODO.


Modified: trunk/src/en/TODO
==============================================================================
--- trunk/src/en/TODO	(original)
+++ trunk/src/en/TODO	Thu Jul  7 03:54:55 2005
@@ -110,12 +110,6 @@
 
   * appA: explain why 'svn commit; svn log' won't show the commit.  [BEN]
 
-  * ch07: best-practice for svn:externals -- always use a specific
-    revision number in externals definitions so that tracking the
-    external is done more judiciously, and so that backdating your own
-    project will also backdate the external. [Mike]
-
-
 ============================================================================
 VOTING FOR TOOLS TO BE MENTIONED IN APPENDIX C
 ============================================================================

Modified: trunk/src/en/book/ch07.xml
==============================================================================
--- trunk/src/en/book/ch07.xml	(original)
+++ trunk/src/en/book/ch07.xml	Thu Jul  7 03:54:55 2005
@@ -2669,6 +2669,24 @@
       subdirectories to display the status of the external items
       themselves.</para>
 
+    <tip>
+      <para>You should strongly consider using explicit revision
+        numbers in all of your externals definitions.  Doing so means
+        that you get to decide when to pull down a different snapshot
+        of external information, and exactly which snapshot to pull.
+        Besides the common sense aspect of not being surprised by
+        changes to third-party repositories that you might not have
+        any control over, using explicit revision numbers also means
+        that as you backdate your working copy to a previous
+        revision, your externals definitions will also revert to the
+        way they looked in that previous revision, which in turn means
+        that the external working copies will be updated to match they
+        way <emphasis>they</emphasis> looked back when your repository was
+        at that previous revision.  For software projects, this could
+        be the difference between a successful and a failed build of
+        an older snapshot of your complex codebase.</para>
+    </tip>
+
     <para>The support that exists for externals definitions in
       Subversion today can be a little misleading, though.  First, an
       externals definition can only point to directories, not files.
@@ -2697,8 +2715,8 @@
       copy</command> to branch that line to some new location
       <filename>/branches/my-branch</filename>, the externals
       definitions on items in your new branch will still refer to
-      versioned resources in <filename>/trunk</filename>.  Also, be
-      aware that if you need to re-parent your working copy (using
+      versioned resources in <filename>/trunk</filename>.  Be aware,
+      too, that if you need to re-parent your working copy (using
       <command>svn switch --relocate</command>), externals definitions
       will <emphasis>not</emphasis> also be re-parented.</para>