From 431b0b97f98ef2805efe1d72518ed707e75503e9 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Thu, 30 Nov 2017 15:43:56 -0500 Subject: [PATCH] upgrading the upgrade docs --- setup/flex.rst | 2 ++ setup/upgrade_major.rst | 30 +++++++++++++++--------------- setup/upgrade_minor.rst | 8 ++++---- setup/upgrade_patch.rst | 4 ++-- 4 files changed, 23 insertions(+), 21 deletions(-) diff --git a/setup/flex.rst b/setup/flex.rst index c220d9efc41..c6a92a9d7db 100644 --- a/setup/flex.rst +++ b/setup/flex.rst @@ -124,6 +124,8 @@ Symfony application by executing the following command: recommended since Symfony 3.3. Use the Composer ``create-project`` command instead. +.. _upgrade-to-flex: + Upgrading Existing Applications to Flex --------------------------------------- diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst index 879fb6b900a..14bbceef458 100644 --- a/setup/upgrade_major.rst +++ b/setup/upgrade_major.rst @@ -1,7 +1,7 @@ .. index:: single: Upgrading; Major Version -Upgrading a Major Version (e.g. 2.7.0 to 3.0.0) +Upgrading a Major Version (e.g. 3.4.0 to 4.0.0) =============================================== Every two years, Symfony releases a new major version release (the first number @@ -30,10 +30,10 @@ backwards incompatible 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 +When the major version is released (e.g. 4.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. +3.4.*), you should be able to upgrade without a problem. To help you with this, deprecation notices are triggered whenever you end up using a deprecated feature. When visiting your application in the @@ -95,7 +95,7 @@ done! .. sidebar:: Using the Weak Deprecations Mode Sometimes, you can't fix all deprecations (e.g. something was deprecated - in 2.8 and you still need to support 2.7). In these cases, you can still + in 3.4 and you still need to support 3.3). In these cases, you can still use the bridge to fix as many deprecations as possible and then switch to the weak test mode to make your tests pass again. You can do this by using the ``SYMFONY_DEPRECATIONS_HELPER`` env variable: @@ -113,12 +113,6 @@ done! (you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=weak phpunit``). -.. tip:: - - Some members of the Symfony Community have developed a tool called - `Symfony-Upgrade-Fixer`_ which automatically fixes some of the most common - deprecations found when upgrading from Symfony 2 to Symfony 3. - .. _upgrade-major-symfony-composer: 2) Update to the New Major Version via Composer @@ -133,7 +127,7 @@ Composer by modifying your ``composer.json`` file: "...": "...", "require": { - "symfony/symfony": "3.0.*", + "symfony/symfony": "^4.0", }, "...": "..." } @@ -153,10 +147,16 @@ Next, use Composer to download new versions of the libraries: 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 +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. +4) Updating to the Symfony 4 Flex Directory Structure +----------------------------------------------------- + +When upgrading to Symfony 4, you will probably also want to upgrade to the new +Symfony 4 directory structure so that you can take advantage of Symfony Flex. +This takes some work, but is optional. For details, see :ref:`upgrade-to-flex`. + .. _`Symfony-Upgrade-Fixer`: https://github.com/umpirsky/Symfony-Upgrade-Fixer diff --git a/setup/upgrade_minor.rst b/setup/upgrade_minor.rst index 7c9f185a0a0..1cdf6e70109 100644 --- a/setup/upgrade_minor.rst +++ b/setup/upgrade_minor.rst @@ -1,7 +1,7 @@ .. index:: single: Upgrading; Minor Version -Upgrading a Minor Version (e.g. 2.5.3 to 2.6.1) +Upgrading a Minor Version (e.g. 3.3.3 to 3.4.0) =============================================== If you're upgrading a minor version (where the middle number changes), then @@ -30,7 +30,7 @@ to use the new version: "...": "...", "require": { - "symfony/symfony": "2.6.*", + "symfony/symfony": "3.4.*", }, "...": "...", } @@ -55,7 +55,7 @@ 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`_) +Every version of Symfony comes with an UPGRADE file (e.g. `UPGRADE-3.4.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. @@ -63,4 +63,4 @@ 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 +.. _`UPGRADE-3.4.md`: https://github.com/symfony/symfony/blob/3.4/UPGRADE-3.4.md diff --git a/setup/upgrade_patch.rst b/setup/upgrade_patch.rst index 4c41e304b28..dd27e9c7bb7 100644 --- a/setup/upgrade_patch.rst +++ b/setup/upgrade_patch.rst @@ -1,7 +1,7 @@ .. index:: single: Upgrading; Patch Version -Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1) +Upgrading a Patch Version (e.g. 3.3.2 to 3.3.3) =============================================== When a new patch version is released (only the last number changed), it is a @@ -15,7 +15,7 @@ version is *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 project, your ``composer.json`` included Symfony using a constraint -like ``2.6.*``, where only the *last* version number will change when you +like ``3.3.*``, where only the *last* version number will change when you update. .. tip::