From a3bae94284a86378150ffc9ac08f1946506b52b5 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sun, 7 Dec 2014 20:20:07 -0500 Subject: [PATCH 1/6] Adding a guide about upgrading --- cookbook/upgrading.rst | 127 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 cookbook/upgrading.rst diff --git a/cookbook/upgrading.rst b/cookbook/upgrading.rst new file mode 100644 index 00000000000..15458e4d93f --- /dev/null +++ b/cookbook/upgrading.rst @@ -0,0 +1,127 @@ +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. + +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-compatability breaks or +need to change anything else in your code. + +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 symfony/symfony + +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-compability changes. + +Upgrading a Minor Version (e.g. 2.5.3 to 2.6.0) +----------------------------------------------- + +If you're upgrading a minor version (where the middle number changes), then +you should also *not* encounter significant backwards compability changes. +For details, see our :doc:`/contributing/code/bc`. + +However, some backwards-compability breaks *are* possible, and you'll learn +in a second how to prepare for them. + +There are two steps to upgrading: + +1. :ref:`upgrade-minor-symfony-composer`; +2. :ref:`upgrade-minor-symfony-code`, which includes instructions for each version. + +.. _`upgrade-minor-symfony-composer`: + +Update the Symfony Library +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, you need to update Symfony by modifying your ``composer.json`` to +use the new version: + +.. code-block:: json + + { + "...": "...", + + "require": { + "php": ">=5.3.3", + "symfony/symfony": "~2.6.0", + "...": "... no changes to anything else..." + }, + "...": "...", + } + +Next, update the same as before: + +.. code-block:: bash + + $ composer update symfony/symfony + +Updating a minor version like this should *not* cause any dependency issues, +though it's always possible that an outside library or bundle you're using +didn't support this new version of Symfony at the version you have of that +library. In that case, consult the library: you may need to modify its version +in ``composer.json`` and run a full ``composer update``. + +.. _`upgrade-minor-symfony-code`: + +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, along with some other +details. + +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`. + +Check the `UPGRADE-2.6`_ document for details. Highlights: + +* If you're using PdoSessionStorage, there was a change in the session schema + that **requires** your session table to be updated. See :doc:`/cookbook/configuration/pdo_session_storage`. + +* Symfony 2.6 comes with a great new `dump`_ function. To use it, you'll + need to add the new ``DebugBundle`` to your ``AppKernel``. See + `UPGRADE-2.6-DebugBundle`_ for details. + +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`. + +Check the `UPGRADE-2.5`_ document for details. Highlights: + +* This version introduced a new Validator API. But, as long as you're using + PHP 5.3.9 or higher, you can configure Symfony in a way that allows you + to use the new API, but still let the old API work (called ``2.5-bc``). + See the `UPGRADE-2.5-Validator`_ for details. + +.. _`UPGRADE-2.5`: https://github.com/symfony/symfony/blob/2.5/UPGRADE-2.5.md +.. _`UPGRADE-2.5-Validator`: https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.5.md#validator +.. _`UPGRADE-2.6`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md +.. _`UPGRADE-2.6-DebugBundle`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md#vardumper-and-debugbundle From b7e9d09efbdc0ea14d766fbc77a710597f0645f8 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 12:31:11 -0500 Subject: [PATCH 2/6] [#4611] Making many tweaks thanks to guys like Javier, Wouter, Christian (xabbuh) and Stof --- cookbook/upgrading.rst | 64 +++++++++++++++++++++++++----------------- 1 file changed, 38 insertions(+), 26 deletions(-) diff --git a/cookbook/upgrading.rst b/cookbook/upgrading.rst index 15458e4d93f..eaa63674532 100644 --- a/cookbook/upgrading.rst +++ b/cookbook/upgrading.rst @@ -1,10 +1,17 @@ -How to Upgrade your Symfony Project +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) ----------------------------------------------- @@ -15,8 +22,10 @@ then it's *really* easy: $ composer update symfony/symfony -That's it! You should not encounter any backwards-compatability breaks or -need to change anything else in your code. +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 Symfony project, your ``composer.json`` included Symfony using a constraint +such as ``2.6.*``, where only the *last* version number changes 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 @@ -24,31 +33,33 @@ safely by running: .. code-block:: bash - $ composer update symfony/symfony + $ 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-compability changes. +to new versions that contain backwards-compatibility breaking changes. + +.. _upgrading-minor-version: Upgrading a Minor Version (e.g. 2.5.3 to 2.6.0) ----------------------------------------------- If you're upgrading a minor version (where the middle number changes), then -you should also *not* encounter significant backwards compability changes. +you should also *not* encounter significant backwards compatibility changes. For details, see our :doc:`/contributing/code/bc`. -However, some backwards-compability breaks *are* possible, and you'll learn +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: -1. :ref:`upgrade-minor-symfony-composer`; -2. :ref:`upgrade-minor-symfony-code`, which includes instructions for each version. +#. :ref:`upgrade-minor-symfony-composer`; +#. :ref:`upgrade-minor-symfony-code`, which includes instructions for each version. .. _`upgrade-minor-symfony-composer`: -Update the Symfony Library -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Update the Symfony Library via Composer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ First, you need to update Symfony by modifying your ``composer.json`` to use the new version: @@ -60,13 +71,13 @@ use the new version: "require": { "php": ">=5.3.3", - "symfony/symfony": "~2.6.0", + "symfony/symfony": "~2.6.*", "...": "... no changes to anything else..." }, "...": "...", } -Next, update the same as before: +Next, use Composer to download new versions of the libraries: .. code-block:: bash @@ -75,12 +86,12 @@ Next, update the same as before: Updating a minor version like this should *not* cause any dependency issues, though it's always possible that an outside library or bundle you're using didn't support this new version of Symfony at the version you have of that -library. In that case, consult the library: you may need to modify its version +library. In that case, consult the library: you may need to modify its version in ``composer.json`` and run a full ``composer update``. .. _`upgrade-minor-symfony-code`: -Updating your Code to work with the new Version +Updating Your Code to Work with the new Version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In theory, you should be done! However, you *may* need to make a few changes @@ -90,8 +101,13 @@ 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, along with some other -details. +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 too? Just find the + UPGRADE-X.X.md file for the appropriate version on the `Symfony Repository`_. Upgrading to Symfony 2.6 ........................ @@ -99,7 +115,8 @@ 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`. -Check the `UPGRADE-2.6`_ document for details. Highlights: +Next, check the `UPGRADE-2.6`_ document for details about any code changes +that you might need to make in your project. * If you're using PdoSessionStorage, there was a change in the session schema that **requires** your session table to be updated. See :doc:`/cookbook/configuration/pdo_session_storage`. @@ -114,14 +131,9 @@ 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`. -Check the `UPGRADE-2.5`_ document for details. Highlights: - -* This version introduced a new Validator API. But, as long as you're using - PHP 5.3.9 or higher, you can configure Symfony in a way that allows you - to use the new API, but still let the old API work (called ``2.5-bc``). - See the `UPGRADE-2.5-Validator`_ for details. +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.5-Validator`: https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.5.md#validator .. _`UPGRADE-2.6`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md -.. _`UPGRADE-2.6-DebugBundle`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md#vardumper-and-debugbundle +.. _`Symfony Repository`: https://github.com/symfony/symfony From e2b925f46215694420b368e9192f007afe5d9090 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 12:56:21 -0500 Subject: [PATCH 3/6] [#4611] Removing a few entries I meant to remove before --- cookbook/upgrading.rst | 7 ------- 1 file changed, 7 deletions(-) diff --git a/cookbook/upgrading.rst b/cookbook/upgrading.rst index eaa63674532..9794b791815 100644 --- a/cookbook/upgrading.rst +++ b/cookbook/upgrading.rst @@ -118,13 +118,6 @@ 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. -* If you're using PdoSessionStorage, there was a change in the session schema - that **requires** your session table to be updated. See :doc:`/cookbook/configuration/pdo_session_storage`. - -* Symfony 2.6 comes with a great new `dump`_ function. To use it, you'll - need to add the new ``DebugBundle`` to your ``AppKernel``. See - `UPGRADE-2.6-DebugBundle`_ for details. - Upgrading to Symfony 2.5 ........................ From 2bee7cc013a5ee00f64cd293b4291f1c0561c528 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 12:57:00 -0500 Subject: [PATCH 4/6] Basically copying a section about upgrading other libraries down into the minor version section --- cookbook/upgrading.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/cookbook/upgrading.rst b/cookbook/upgrading.rst index 9794b791815..f88b191af9a 100644 --- a/cookbook/upgrading.rst +++ b/cookbook/upgrading.rst @@ -35,7 +35,7 @@ safely by running: $ composer update -But beware. If you have some bad version constraints in your ``composer.json``, +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. @@ -83,11 +83,17 @@ Next, use Composer to download new versions of the libraries: $ composer update symfony/symfony -Updating a minor version like this should *not* cause any dependency issues, -though it's always possible that an outside library or bundle you're using -didn't support this new version of Symfony at the version you have of that -library. In that case, consult the library: you may need to modify its version -in ``composer.json`` and run a full ``composer 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. .. _`upgrade-minor-symfony-code`: @@ -130,3 +136,5 @@ 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 \ No newline at end of file From d91552690eba41d8b3a7dfc164732ca72a40251a Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 13:08:55 -0500 Subject: [PATCH 5/6] [#4611] A few more tweaks and fixes --- cookbook/upgrading.rst | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/cookbook/upgrading.rst b/cookbook/upgrading.rst index f88b191af9a..0dc36fcd160 100644 --- a/cookbook/upgrading.rst +++ b/cookbook/upgrading.rst @@ -24,12 +24,13 @@ then it's *really* easy: 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 Symfony project, your ``composer.json`` included Symfony using a constraint -such as ``2.6.*``, where only the *last* version number changes when you update. +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: +good job with your `version constraints`_ in ``composer.json``, you can do +this safely by running: .. code-block:: bash @@ -41,7 +42,7 @@ to new versions that contain backwards-compatibility breaking changes. .. _upgrading-minor-version: -Upgrading a Minor Version (e.g. 2.5.3 to 2.6.0) +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 @@ -53,16 +54,16 @@ in a second how to prepare for them. There are two steps to upgrading: -#. :ref:`upgrade-minor-symfony-composer`; -#. :ref:`upgrade-minor-symfony-code`, which includes instructions for each version. +:ref:`upgrade-minor-symfony-composer`; +:ref:`upgrade-minor-symfony-code` .. _`upgrade-minor-symfony-composer`: -Update the Symfony Library via Composer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +1) Update the Symfony Library via Composer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -First, you need to update Symfony by modifying your ``composer.json`` to -use the new version: +First, you need to update Symfony by modifying your ``composer.json`` file +to use the new version: .. code-block:: json @@ -71,7 +72,7 @@ use the new version: "require": { "php": ">=5.3.3", - "symfony/symfony": "~2.6.*", + "symfony/symfony": "2.6.*", "...": "... no changes to anything else..." }, "...": "...", @@ -84,8 +85,8 @@ Next, use Composer to download new versions of the libraries: $ 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: +good job with your `version constraints`_ in ``composer.json``, you can do +this safely by running: .. code-block:: bash @@ -97,8 +98,8 @@ to new versions that contain backwards-compatibility breaking changes. .. _`upgrade-minor-symfony-code`: -Updating Your Code to Work with the new Version -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 @@ -112,7 +113,7 @@ to read to see if you need any code changes. .. tip:: - Don't see the version here that you're upgrading too? Just find the + 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 From 341e530294ba8368d98b49ef3ae9413fec33601c Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 3 Jan 2015 13:10:54 -0500 Subject: [PATCH 6/6] Adding missing index/map documents --- cookbook/index.rst | 1 + cookbook/map.rst.inc | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/cookbook/index.rst b/cookbook/index.rst index 1a088c672dd..1880a705000 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -28,6 +28,7 @@ The Cookbook symfony1 templating/index testing/index + upgrading validation/index web_server/index web_services/index diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 24a0cd78371..239d51408bb 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -200,6 +200,10 @@ * (email) :doc:`/cookbook/email/testing` * (form) :doc:`/cookbook/form/unit_testing` +* **Upgrading** + + * :doc:`/cookbook/upgrading` + * :doc:`/cookbook/validation/index` * :doc:`/cookbook/validation/custom_constraint`