From 6a90c9b7519d97f5ba7e809d0c81320f966cbd04 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Tue, 10 Mar 2015 11:02:47 +0100 Subject: [PATCH] Created 'upgrade' cookbook section --- cookbook/index.rst | 2 +- cookbook/map.rst.inc | 5 +- cookbook/upgrade/_update_all_packages.rst.inc | 16 ++ cookbook/upgrade/index.rst | 17 +++ cookbook/upgrade/minor_version.rst | 63 ++++++++ cookbook/upgrade/patch_version.rst | 26 ++++ cookbook/upgrading.rst | 141 ------------------ redirection_map | 1 + 8 files changed, 127 insertions(+), 144 deletions(-) create mode 100644 cookbook/upgrade/_update_all_packages.rst.inc create mode 100644 cookbook/upgrade/index.rst create mode 100644 cookbook/upgrade/minor_version.rst create mode 100644 cookbook/upgrade/patch_version.rst delete mode 100644 cookbook/upgrading.rst diff --git a/cookbook/index.rst b/cookbook/index.rst index 03d29060c7f..2e0de5df7ef 100644 --- a/cookbook/index.rst +++ b/cookbook/index.rst @@ -28,7 +28,7 @@ The Cookbook symfony1 templating/index testing/index - upgrading + upgrade/index validation/index web_server/index web_services/index diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 6c8e5d59d89..92bc715cee4 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -201,9 +201,10 @@ * (email) :doc:`/cookbook/email/testing` * (form) :doc:`/cookbook/form/unit_testing` -* **Upgrading** +* :doc:`/cookbook/upgrading/index` - * :doc:`/cookbook/upgrading` + * :doc:`/cookbook/upgrading/patch_version` + * :doc:`/cookbook/upgrading/minor_version` * :doc:`/cookbook/validation/index` diff --git a/cookbook/upgrade/_update_all_packages.rst.inc b/cookbook/upgrade/_update_all_packages.rst.inc new file mode 100644 index 00000000000..49d82e9fe12 --- /dev/null +++ b/cookbook/upgrade/_update_all_packages.rst.inc @@ -0,0 +1,16 @@ +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 + +.. caution:: + + Beware, if you have some bad `version constraints`_ in your + ``composer.json`` (e.g. ``dev-master``), this could upgrade some + non-Symfony libraries to new versions that contain backwards-compatibility + breaking changes. + +.. _`versino constraints`: https://getcomposer.org/doc/01-basic-usage.md#package-versions diff --git a/cookbook/upgrade/index.rst b/cookbook/upgrade/index.rst new file mode 100644 index 00000000000..fe4aeca3b4e --- /dev/null +++ b/cookbook/upgrade/index.rst @@ -0,0 +1,17 @@ +.. index:: + single: Upgrading + +Upgrading +========= + +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 three types of upgrades, all needing a little different preparation: + +.. toctree:: + :maxdepth: 2 + + /cookbook/upgrade/patch_version + /cookbook/upgrade/minor_version diff --git a/cookbook/upgrade/minor_version.rst b/cookbook/upgrade/minor_version.rst new file mode 100644 index 00000000000..4a5a0fa023e --- /dev/null +++ b/cookbook/upgrade/minor_version.rst @@ -0,0 +1,63 @@ +.. index:: + single: 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 *not* encounter significant backwards compatibility changes. For +details, see the :doc:`Symfony backwards compatibility promise `. + +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 a minor version: + +#. :ref:`Update the Symfony library via Composer `; +#. :ref:`Update your code to work with the new version `. + +.. _`upgrade-minor-symfony-composer`: + +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": { + "symfony/symfony": "2.6.*", + }, + "...": "...", + } + +Next, use Composer to download new versions of the libraries: + +.. code-block:: bash + + $ composer update symfony/symfony + +.. include:: /cookbook/upgrade/_update_all_packages.rst.inc + +.. _`upgrade-minor-symfony-code`: + +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. While that's just fine, +if you know about these deprecations, you can start to fix them over time. + +Every version of Symfony comes with an UPGRADE file included in the Symfony +directory that describes these changes. If you follow the instructions in the +document and update your code accordingly, it should be save to update in the +future. + +These documents can also be found in the `Symfony Repository`_. + +.. _`Symfony Repository`: https://github.com/symfony/symfony diff --git a/cookbook/upgrade/patch_version.rst b/cookbook/upgrade/patch_version.rst new file mode 100644 index 00000000000..2968aa22c77 --- /dev/null +++ b/cookbook/upgrade/patch_version.rst @@ -0,0 +1,26 @@ +.. index:: + single: Upgrading; Patch Version + +Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1) +=============================================== + +When a new patch version is released (only the last number changed), it is a +release that only contains bug fixes. This means that upgrading to a new patch +version is *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. + +.. tip:: + + It is recommended to update to a new patch version as soon as possible, as + important bugs and security leaks may be fixed in these new releases. + +.. include:: /cookbook/upgrade/_update_all_packages.rst.inc diff --git a/cookbook/upgrading.rst b/cookbook/upgrading.rst deleted file mode 100644 index 0dc36fcd160..00000000000 --- a/cookbook/upgrading.rst +++ /dev/null @@ -1,141 +0,0 @@ -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` - -.. _`upgrade-minor-symfony-composer`: - -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. - -.. _`upgrade-minor-symfony-code`: - -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 \ No newline at end of file diff --git a/redirection_map b/redirection_map index 2d782f924fb..e325f7896a9 100644 --- a/redirection_map +++ b/redirection_map @@ -23,3 +23,4 @@ /cookbook/console/generating_urls /cookbook/console/sending_emails /components/yaml /components/yaml/introduction /components/templating /components/templating/introduction +/cookbook/upgrading /cookbook/upgrade/index