diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst index 2d2a5f9cc94..95613bd1763 100644 --- a/contributing/code/bc.rst +++ b/contributing/code/bc.rst @@ -1,4 +1,4 @@ -Our backwards Compatibility Promise +Our Backwards Compatibility Promise =================================== Ensuring smooth upgrades of your projects is our first priority. That's why 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..e268cecbe39 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -201,9 +201,11 @@ * (email) :doc:`/cookbook/email/testing` * (form) :doc:`/cookbook/form/unit_testing` -* **Upgrading** +* :doc:`/cookbook/upgrade/index` - * :doc:`/cookbook/upgrading` + * :doc:`/cookbook/upgrade/patch_version` + * :doc:`/cookbook/upgrade/minor_version` + * :doc:`/cookbook/upgrade/major_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..95e1c63f954 --- /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 unspecific `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. + +.. _`version 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..b943f2ae32a --- /dev/null +++ b/cookbook/upgrade/index.rst @@ -0,0 +1,18 @@ +.. 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 + /cookbook/upgrade/major_version diff --git a/cookbook/upgrade/major_version.rst b/cookbook/upgrade/major_version.rst new file mode 100644 index 00000000000..10fcafbbf83 --- /dev/null +++ b/cookbook/upgrade/major_version.rst @@ -0,0 +1,112 @@ +.. index:: + single: Upgrading; Major Version + +Upgrading a Major Version (e.g. 2.7.0 to 3.0.0) +=============================================== + +Every few years, Symfony releases a new major version release (the first number +changes). These releases are the trickiest to upgrade, as they are allowed to +contain BC breaks. However, Symfony tries to make this upgrade process as +smooth as possible. + +This means that you can update most of your code before the major release is +actually released. This is called making your code *future compatible*. + +There are a couple of steps to upgrading a major version: + +#. :ref:`Make your code deprecation free `; +#. :ref:`Update to the new major version via Composer `. +#. :ref:`Update your code to work with the new version ` + +.. _upgrade-major-symfony-deprecations: + +1) Make your Code Deprecation Free +---------------------------------- + +During the lifecycle of a major release, new features are added and method +signatures and public API usages are changed. However, +:doc:`minor versions ` should not contain any +backwards compatibility changes. To accomplish this, the "old" (e.g. functions, +classes, etc) code still works, but is marked as *deprecated*, indicating that +it will be removed/changed in the future and that you should stop using it. + +When the major version is released (e.g. 3.0.0), all deprecated features and +functionality are removed. So, as long as you've updated your code to stop +using these deprecated features in the last version before the major (e.g. +2.8.*), you should be able to upgrade without a problem. + +To help you with this, the last minor releases will trigger deprecated notices. +For example, 2.7 and 2.8 trigger deprecated notices. When visiting your +application in the :doc:`dev environment ` +in your browser, these notices are shown in the web dev toolbar: + +.. image:: /images/cookbook/deprecations-in-profiler.png + +Deprecations in PHPUnit +~~~~~~~~~~~~~~~~~~~~~~~ + +By default, PHPUnit will handle deprecation notices as real errors. This means +that all tests are aborted because it uses a BC layer. + +To make sure this doesn't happen, you can install the PHPUnit bridge: + +.. code-block:: bash + + $ composer require symfony/phpunit-bridge + +Now, your tests execute normally and a nice summary of the deprecation notices +is displayed at the end of the test report: + +.. code-block:: text + + $ phpunit + ... + + OK (10 tests, 20 assertions) + + Remaining deprecation notices (6) + + The "request" service is deprecated and will be removed in 3.0. Add a typehint for + Symfony\Component\HttpFoundation\Request to your controller parameters to retrieve the + request instead: 6x + 3x in PageAdminTest::testPageShow from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin + 2x in PageAdminTest::testPageList from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin + 1x in PageAdminTest::testPageEdit from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin + +.. _upgrade-major-symfony-composer: + +2) Update to the New Major Version via Composer +----------------------------------------------- + +If your code is deprecation free, you can update the Symfony library via +Composer by modifying your ``composer.json`` file: + +.. code-block:: json + + { + "...": "...", + + "require": { + "symfony/symfony": "3.0.*", + }, + "...": "...", + } + +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-major-symfony-after: + +3) Update your Code to Work with the New Version +------------------------------------------------ + +There is a good chance that you're done now! However, the next major version +*may* also contain new BC breaks as a BC layer is not always a possibility. +Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major version) +included in the Symfony repository for any BC break that you need to be aware +of. diff --git a/cookbook/upgrade/minor_version.rst b/cookbook/upgrade/minor_version.rst new file mode 100644 index 00000000000..55b63bb0580 --- /dev/null +++ b/cookbook/upgrade/minor_version.rst @@ -0,0 +1,64 @@ +.. 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 (e.g. `UPGRADE-2.7.md`_) +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 +safe to update in the future. + +These documents can also be found in the `Symfony Repository`_. + +.. _`Symfony Repository`: https://github.com/symfony/symfony +.. _`UPGRADE-2.7.md`: https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.7.md 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/images/cookbook/deprecations-in-profiler.png b/images/cookbook/deprecations-in-profiler.png new file mode 100644 index 00000000000..7b32d59cb05 Binary files /dev/null and b/images/cookbook/deprecations-in-profiler.png differ 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