From 76b75713b5da5e7384c60fbf952da225f156be12 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 14 Jan 2012 09:35:58 -0600 Subject: [PATCH] [cookbook] Tweaking the new entry on using subversion, making one section shared, etc --- cookbook/index.rst | 1 + cookbook/map.rst.inc | 1 + cookbook/workflow/_vendor_deps.rst.inc | 49 +++++++++++ cookbook/workflow/new_project_git.rst | 39 +-------- cookbook/workflow/new_project_svn.rst | 107 +++++++------------------ 5 files changed, 83 insertions(+), 114 deletions(-) create mode 100644 cookbook/workflow/_vendor_deps.rst.inc diff --git a/cookbook/index.rst b/cookbook/index.rst index 3e434db2602..5aa10de0365 100644 --- 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 index d0ddbe23d41..fe678521c25 100644 --- 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 new file mode 100644 index 00000000000..d36d14d7d26 --- /dev/null +++ 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. \ No newline at end of file diff --git a/cookbook/workflow/new_project_git.rst b/cookbook/workflow/new_project_git.rst index 4d3ad12a387..9a007c4e4d3 100644 --- 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 index 0472053154d..8fd62424283 100644 --- 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,46 +121,7 @@ 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: @@ -174,7 +129,7 @@ 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