Added a new article about using/installing unstable Symfony versions

cookbook/index.rst

@@ -18,6 +18,7 @@ The Cookbook
     event_dispatcher/index
     form/index
     frontend/index
+    install/index
     logging/index
     profiler/index
     request/index

cookbook/install/index.rst

@@ -0,0 +1,8 @@
+Install and Upgrade
+===================
+
+.. toctree::
+    :maxdepth: 2
+
+    upgrading
+    unstable_versions

cookbook/install/unstable_versions.rst

@@ -0,0 +1,80 @@
+How to Install or Upgrade to the Latest, Unreleased Symfony Version
+===================================================================
+
+In this article, you'll learn how to install and use new Symfony versions before
+they are released as stable versions.
+
+Creating a New Project Based on an Unstable Symfony Version
+-----------------------------------------------------------
+
+Suppose that Symfony 2.7 version hasn't been released yet and you want to create
+a new project to test its features. First, :doc:`install the Composer </cookbook/composer>`
+package manager. Then, open a command console, enter your project's directory and
+execute the following command:
+
+.. code-block:: bash
+
+    $ composer create-project symfony/framework-standard-edition my_project "2.7.*" --stability=dev
+
+Once the command finishes its execution, you'll have a new Symfony project created
+in the ``my_project/`` directory and based on the most recent code found in the
+``2.7`` branch.
+
+If you want to test a beta version, use ``beta`` as the value of the ``stability``
+option:
+
+.. code-block:: bash
+
+    $ composer create-project symfony/framework-standard-edition my_project "2.7.*" --stability=beta
+
+Upgrading your Project to an Unstable Symfony Version
+-----------------------------------------------------
+
+Suppose again that Symfony 2.7 hasn't been released yet and you want to upgrade
+an existing application to test that your project works with it.
+
+First, open the ``composer.json`` file located in the root directory of your
+project. Then, edit the value of the version defined for the ``symfony/symfony``
+dependency as follows:
+
+.. code-block:: json
+
+    {
+        "require": {
+            // ...
+            "symfony/symfony" : "2.7.*@dev"
+        }
+    }
+
+Finally, open a command console, enter your project directory and execute the
+following command to update your project dependencies:
+
+.. code-block:: bash
+
+    $ composer update symfony/symfony
+
+If you prefer to test a Symfony beta version, replace the ``"2.7.*@dev"`` constraint
+by ``"2.7.0-beta1"`` to install a specific beta number or ``2.7.*@beta`` to get
+the most recent beta version.
+
+After upgrading the Symfony version, read the :doc:`Symfony Upgrading Guide </cookbook/upgrade/index>`
+to learn how you should proceed to update your application's code in case the new
+Symfony version has deprecated some of its features.
+
+.. tip::
+
+    If you use Git to manage the project's code, it's a good practice to create
+    a new branch to test the new Symfony version. This solution avoids introducing
+    any issue in your application and allows you to test the new version with
+    total confidence:
+
+    .. code-block:: bash
+
+        $ cd projects/my_project/
+        $ git checkout -b testing_new_symfony
+        # ... update composer.json configuration
+        $ composer update symfony/symfony
+
+        # ... after testing the new Symfony version
+        $ git checkout master
+        $ git branch -D testing_new_symfony

cookbook/install/upgrading.rst

@@ -0,0 +1,137 @@
+How to Upgrade Your Symfony Project
+===================================
+
+So a new Symfony release has come out and you want to upgrade, great! Fortunately,
+because Symfony protects backwards-compatibility very closely, this *should*
+be quite easy.
+
+There are two types of upgrades, and both are a little different:
+
+* :ref:`upgrading-patch-version`
+* :ref:`upgrading-minor-version`
+
+.. _upgrading-patch-version:
+
+Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1)
+-----------------------------------------------
+
+If you're upgrading and only the patch version (the last number) is changing,
+then it's *really* easy:
+
+.. code-block:: bash
+
+    $ composer update symfony/symfony
+
+That's it! You should not encounter any backwards-compatibility breaks or
+need to change anything else in your code. That's because when you started
+your project, your ``composer.json`` included Symfony using a constraint
+like ``2.6.*``, where only the *last* version number will change when you
+update.
+
+You may also want to upgrade the rest of your libraries. If you've done a
+good job with your `version constraints`_ in ``composer.json``, you can do
+this safely by running:
+
+.. code-block:: bash
+
+    $ composer update
+
+But beware. If you have some bad `version constraints`_ in your ``composer.json``,
+(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries
+to new versions that contain backwards-compatibility breaking changes.
+
+.. _upgrading-minor-version:
+
+Upgrading a Minor Version (e.g. 2.5.3 to 2.6.1)
+-----------------------------------------------
+
+If you're upgrading a minor version (where the middle number changes), then
+you should also *not* encounter significant backwards compatibility changes.
+For details, see our :doc:`/contributing/code/bc`.
+
+However, some backwards-compatibility breaks *are* possible, and you'll learn
+in a second how to prepare for them.
+
+There are two steps to upgrading:
+
+:ref:`upgrade-minor-symfony-composer`;
+:ref:`upgrade-minor-symfony-code`
+
+1) Update the Symfony Library via Composer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First, you need to update Symfony by modifying your ``composer.json`` file
+to use the new version:
+
+.. code-block:: json
+
+    {
+        "...": "...",
+
+        "require": {
+            "php": ">=5.3.3",
+            "symfony/symfony": "2.6.*",
+            "...": "... no changes to anything else..."
+        },
+        "...": "...",
+    }
+
+Next, use Composer to download new versions of the libraries:
+
+.. code-block:: bash
+
+    $ composer update symfony/symfony
+
+You may also want to upgrade the rest of your libraries. If you've done a
+good job with your `version constraints`_ in ``composer.json``, you can do
+this safely by running:
+
+.. code-block:: bash
+
+    $ composer update
+
+But beware. If you have some bad `version constraints`_ in your ``composer.json``,
+(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries
+to new versions that contain backwards-compatibility breaking changes.
+
+2) Updating Your Code to Work with the new Version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In theory, you should be done! However, you *may* need to make a few changes
+to your code to get everything working. Additionally, some features you're
+using might still work, but might now be deprecated. That's actually ok,
+but if you know about these deprecations, you can start to fix them over
+time.
+
+Every version of Symfony comes with an UPGRADE file that describes these
+changes. Below are links to the file for each version, which you'll need
+to read to see if you need any code changes.
+
+.. tip::
+
+    Don't see the version here that you're upgrading to? Just find the
+    UPGRADE-X.X.md file for the appropriate version on the `Symfony Repository`_.
+
+Upgrading to Symfony 2.6
+........................
+
+First, of course, update your ``composer.json`` file with the ``2.6`` version
+of Symfony as described above in :ref:`upgrade-minor-symfony-composer`.
+
+Next, check the `UPGRADE-2.6`_ document for details about any code changes
+that you might need to make in your project.
+
+Upgrading to Symfony 2.5
+........................
+
+First, of course, update your ``composer.json`` file with the ``2.5`` version
+of Symfony as described above in :ref:`upgrade-minor-symfony-composer`.
+
+Next, check the `UPGRADE-2.5`_ document for details about any code changes
+that you might need to make in your project.
+
+.. _`UPGRADE-2.5`: https://github.com/symfony/symfony/blob/2.5/UPGRADE-2.5.md
+.. _`UPGRADE-2.6`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md
+.. _`Symfony Repository`: https://github.com/symfony/symfony
+.. _`Composer Package Versions`: https://getcomposer.org/doc/01-basic-usage.md#package-versions
+.. _`version constraints`: https://getcomposer.org/doc/01-basic-usage.md#package-versions

cookbook/map.rst.inc

@@ -112,6 +112,11 @@
 
   * :doc:`/cookbook/frontend/bower`
 
+* :doc:`/cookbook/install/index`
+
+  * :doc:`/cookbook/install/upgrading`
+  * :doc:`/cookbook/install/unstable_versions`
+
 * :doc:`/cookbook/logging/index`
 
   * :doc:`/cookbook/logging/monolog`

redirection_map

@@ -14,6 +14,7 @@
 /cookbook/service_container/parentservices /components/dependency_injection/parentservices
 /cookbook/service_container/factories /components/dependency_injection/factories
 /cookbook/service_container/tags /components/dependency_injection/tags
+/cookbook/upgrading /cookbook/install/upgrading
 /reference/configuration/mongodb /bundles/DoctrineMongoDBBundle/config
 /reference/YAML /components/yaml
 /components/dependency_injection /components/dependency_injection/introduction