[cookbook] Tweaking the new entry on using subversion, making one section shared, etc

weaverryan · weaverryan · commit 76b75713b5da · 2012-01-14T09:35:58.000-06:00
diff --git a/cookbook/index.rst b/cookbook/index.rst
@@ -5,6 +5,7 @@ Cookbook
     :hidden:
 
     workflow/new_project_git
+    workflow/new_project_svn
 
     controller/error_pages
     controller/service
diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -1,6 +1,7 @@
 * **Workflow**
 
   * :doc:`/cookbook/workflow/new_project_git`
+  * :doc:`/cookbook/workflow/new_project_svn`
 
 * **Controllers**
 
diff --git a/cookbook/workflow/_vendor_deps.rst.inc b/cookbook/workflow/_vendor_deps.rst.inc
@@ -0,0 +1,49 @@
+Managing Vendor Libraries with bin/vendors and deps
+---------------------------------------------------
+
+Every Symfony project uses a group of third-party "vendor" libraries. One
+way or another the goal is to download these files into your ``vendor/``
+directory and, ideally, to give you some sane way to manage the exact version
+you need for each.
+
+By default, these libraries are downloaded by running a ``php bin/vendors install``
+"downloader" script. This script reads from the ``deps`` file at the root
+of your project. This is an ini-formatted script, which holds a list of each
+of the external libraries you need, the directory each should be downloaded to,
+and (optionally) the version to be downloaded. The ``bin/vendors`` script
+uses ``git`` to downloaded these, solely because these external libraries
+themselves tend to be stored via git. The ``vin/vendors`` script also reads
+the ``deps.lock`` file, which allows you to pin each library to an exact
+git commit hash.
+
+It's important to realize that these vendor libraries are *not* actually part
+of *your* repository. Instead, they're simply un-tracked files that are downloaded
+into the ``vendor/`` directory by the ``bin/vendors`` script. But since all
+the information needed to download these files is saved in ``deps`` and ``deps.lock``
+(which *are* stored) in our repository), any other developer can use our
+project, run ``php bin/vendors install``, and download the exact same set
+of vendor libraries. This means that you're controlling exactly what each
+vendor library looks like, without needing to actually commit them to *your*
+repository.
+
+So, whenever a developer uses your project, he/she should run the ``php bin/vendors install``
+script to ensure that all of the needed vendor libraries are downloaded.
+
+.. sidebar:: Upgrading Symfony
+
+    Since Symfony is just a group of third-party libraries and third-party
+    libraries are entirely controlled through ``deps`` and ``deps.lock``,
+    upgrading Symfony means simply upgrading each of these files to match
+    their state in the latest Symfony Standard Edition.
+
+    Of course, if you've added new entries to ``deps`` or ``deps.lock``, be sure
+    to replace only the original parts (i.e. be sure not to also delete any of
+    your custom entries).
+
+.. caution::
+
+    There is also a ``php bin/vendors update`` command, but this has nothing
+    to do with upgrading your project and you will normally not need to use
+    it. This command is used to freeze the versions of all of your vendor libraries
+    by updating them to the version specified in ``deps`` and recording it
+    into the ``deps.lock`` file.
diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst
@@ -79,44 +79,7 @@ to learn more about how to configure and develop inside your application.
 
 .. _cookbook-managing-vendor-libraries:
 
-Managing Vendor Libraries with bin/vendors and deps
----------------------------------------------------
-
-Every Symfony project uses a large group of third-party "vendor" libraries.
-
-By default, these libraries are downloaded by running the ``php bin/vendors install``
-script. This script reads from the ``deps`` file, and downloads the given
-libraries into the ``vendor/`` directory. It also reads ``deps.lock`` file,
-pinning each library listed there to the exact git commit hash.
-
-In this setup, the vendors libraries aren't part of your git repository,
-not even as submodules. Instead, we rely on the ``deps`` and ``deps.lock``
-files and the ``bin/vendors`` script to manage everything. Those files are
-part of your repository, so the necessary versions of each third-party library
-are version-controlled in git, and you can use the vendors script to bring
-your project up to date.
-
-Whenever a developer clones a project, he/she should run the ``php bin/vendors install``
-script to ensure that all of the needed vendor libraries are downloaded.
-
-.. sidebar:: Upgrading Symfony
-
-    Since Symfony is just a group of third-party libraries and third-party
-    libraries are entirely controlled through ``deps`` and ``deps.lock``,
-    upgrading Symfony means simply upgrading each of these files to match
-    their state in the latest Symfony Standard Edition.
-
-    Of course, if you've added new entries to ``deps`` or ``deps.lock``, be sure
-    to replace only the original parts (i.e. be sure not to also delete any of
-    your custom entries).
-
-.. caution::
-
-    There is also a ``php bin/vendors update`` command, but this has nothing
-    to do with upgrading your project and you will normally not need to use
-    it. This command is used to freeze the versions of all of your vendor libraries
-    by updating them to the version specified in ``deps`` and recording it
-    into the ``deps.lock`` file.
+.. include:: _vendor_deps.rst.inc
 
 Vendors and Submodules
 ~~~~~~~~~~~~~~~~~~~~~~
diff --git a/cookbook/workflow/new_project_svn.rst b/cookbook/workflow/new_project_svn.rst
@@ -8,23 +8,22 @@ How to Create and store a Symfony2 Project in Subversion
 
 Once you've read through :doc:`/book/page_creation` and become familiar with
 using Symfony, you'll no-doubt be ready to start your own project. The
-preferred method to manage Symfony2 projects is using `git`_ but some people
-are stuck with `Subversion`_ and don't have a choice. In this cookbook article,
-you'll learn how to manage your project using `svn`_ in a similar manner you
+preferred method to manage Symfony2 projects is using `git`_ but some prefer
+to use `Subversion`_ which is totally fine!. In this cookbook article, you'll
+learn how to manage your project using `svn`_ in a similar manner you
 would do with `git`_.
 
-.. caution::
+.. tip::
 
-    This is **a** method to import your Symfony2 project in a Subversion
+    This is **a** method to tracking your Symfony2 project in a Subversion
     repository. There are several ways to do and this one is simply one that
-    works. Furthermore, it is quite complex to do so you should probably
-    consider using `git`_ anyway.
+    works.
 
-Subversion repository
----------------------
+The Subversion Repository
+-------------------------
 
 For this article we will suppose that your repository layout follows the
-widespread standard structure :
+widespread standard structure:
 
 .. code-block:: text
 
@@ -35,16 +34,16 @@ widespread standard structure :
 
 .. tip::
 
-    Most of the subversion hosting should follow this standard practice. This
+    Most subversion hosting should follow this standard practice. This
     is the recommended layout in `Version Control with Subversion`_ and the
     layout used by most free hosting (see :ref:`svn-hosting`).
 
 Initial Project Setup
 ---------------------
 
-To get started, you'll need to download Symfony2 and get the basic Subversion setup :
+To get started, you'll need to download Symfony2 and get the basic Subversion setup:
 
-1. Download the `Symfony2 Standard Edition`_ without vendors.
+1. Download the `Symfony2 Standard Edition`_ without or without vendors.
 
 2. Unzip/untar the distribution. It will create a folder called Symfony with
    your new project structure, config files, etc. Rename it to whatever you
@@ -63,34 +62,28 @@ To get started, you'll need to download Symfony2 and get the basic Subversion se
 
         $ mv Symfony/* myproject/
 
-5. Let's now set the ignore rules, this is the complex part compared to `git`_.
-   You need to add some specific files/folders to the subversion repository and
-   edit ``svn:ignore`` properties:
+5. Let's now set the ignore rules. Not everything *should* be stored in your
+   subversion repository. Some files (like the cache) are generated and
+   others (like the database configuration) are meant to be customized
+   on each machine. This makes use of the ``svn:ignore`` property, so that
+   we can ignore specific files.
 
     .. code-block:: bash
 
         $ cd myproject/
         $ svn add --depth=empty app app/cache app/logs app/config web
-        $ svn propedit svn:ignore .
-        vendor
-        $ svn propedit svn:ignore app/
-        bootstrap*
-        $ svn propedit svn:ignore app/config/
-        parameters.ini
-        $ svn propedit svn:ignore app/cache/
-        *
-        $ svn propedit svn:ignore app/logs/
-        *
-        $ svn propedit svn:ignore web
-        bundles
-        $ svn ci -m "commit basic symfony ignore list (vendor, app/bootstrap*, app/config/parameters.ini, app/cache/*, app/logs/*, web/bundles)"
 
-.. tip::
+        $ svn propset svn:ignore "vendor" .
+        $ svn propset svn:ignore "bootstrap*" app/
+        $ svn propset svn:ignore "parameters.ini" app/config/
+        $ svn propset svn:ignore "*" app/cache/
+        $ svn propset svn:ignore "*" app/logs/
 
-    This part is a bit painful but this is the only way to make sure that those
-    files and folders will **never** appear in your project repository.
+        $ svn propset svn:ignore "bundles" web
 
-6. The rest of the files can now be added and commited to the project:
+        $ svn ci -m "commit basic symfony ignore list (vendor, app/bootstrap*, app/config/parameters.ini, app/cache/*, app/logs/*, web/bundles)"
+
+6. The rest of the files can now be added and committed to the project:
 
     .. code-block:: bash
 
@@ -113,9 +106,10 @@ To get started, you'll need to download Symfony2 and get the basic Subversion se
 .. tip::
 
     `git`_ has to be installed to run ``bin/vendors``, this is the protocol
-    used to fetch vendor libraries.
+    used to fetch vendor libraries. This only means that ``git`` is used as
+    a tool to basically help download the libraries in the ``vendor/`` directory.
 
-At this point, you have a fully-functional Symfony2 project, followed in your
+At this point, you have a fully-functional Symfony2 project stored in your
 Subversion repository. The development can start with commits in the Subversion
 repository.
 
@@ -127,54 +121,15 @@ to learn more about how to configure and develop inside your application.
     The Symfony2 Standard Edition comes with some example functionality. To
     remove the sample code, follow the instructions on the `Standard Edition Readme`_.
 
-.. _cookbook-managing-vendor-libraries:
-
-Managing Vendor Libraries with bin/vendors and deps
----------------------------------------------------
-
-Every Symfony project uses a large group of third-party "vendor" libraries.
-
-By default, these libraries are downloaded by running the ``php bin/vendors install``
-script. This script reads from the ``deps`` file, and downloads the given
-libraries into the ``vendor/`` directory. It also reads ``deps.lock`` file,
-pinning each library listed there to the exact git commit hash.
-
-In this setup, the vendors libraries aren't part of your repository,
-not even as submodules. Instead, we rely on the ``deps`` and ``deps.lock``
-files and the ``bin/vendors`` script to manage everything. Those files are
-part of your repository, so the necessary versions of each third-party library
-are version-controlled, and you can use the vendors script to bring
-your project up to date.
-
-Whenever a developer clones a project, he/she should run the ``php bin/vendors install``
-script to ensure that all of the needed vendor libraries are downloaded.
-
-.. sidebar:: Upgrading Symfony
-
-    Since Symfony is just a group of third-party libraries and third-party
-    libraries are entirely controlled through ``deps`` and ``deps.lock``,
-    upgrading Symfony means simply upgrading each of these files to match
-    their state in the latest Symfony Standard Edition.
-
-    Of course, if you've added new entries to ``deps`` or ``deps.lock``, be sure
-    to replace only the original parts (i.e. be sure not to also delete any of
-    your custom entries).
-
-.. caution::
-
-    There is also a ``php bin/vendors update`` command, but this has nothing
-    to do with upgrading your project and you will normally not need to use
-    it. This command is used to freeze the versions of all of your vendor libraries
-    by updating them to the version specified in ``deps`` and recording it
-    into the ``deps.lock`` file.
+.. include:: _vendor_deps.rst.inc
 
 .. _svn-hosting:
 
 Subversion hosting solutions
 ----------------------------
 
 The biggest difference between `git`_ and `svn`_ is that Subversion *needs* a
-central repository to work. You then have several solutions :
+central repository to work. You then have several solutions:
 
 - Self hosting: create your own repository and access it either through the
   filesystem or the network. To help in this task you can read `Version Control
